sophophilix/python-standards

Python 표준

이 스킬은 Python 툴링과 프로젝트 전반 규칙에 대한 단일 진실 공급원입니다. 아키텍처, 스타일, 테스트, 리뷰 스킬은 이 스킬을 참조하고 내용을 중복하지 않아야 합니다.

프로젝트 문서를 작성할 때는 technical-writing도 로드하세요. 이 스킬은 humanizer를 호출하며 문서 위치, 타임스탬프, 리뷰 메타데이터, 접근성, 작성 품질을 관리합니다.

규칙 우선순위

다음 순서로 규칙을 적용하세요:

1. 명시적인 사용자 또는 조직 요구사항
2. 저장소 구성 및 승인된 아키텍처 결정
3. 이 스킬 및 다른 Python 스킬
4. PEP 8 및 도구 기본값

보안 기준을 자동으로 약화시키지 마십시오. 필요한 예외 사항은 그 범위, 위험도, 소유자(알고 있는 경우), 제거 조건과 함께 프로젝트 결정 기록에 기록하세요.

런타임 및 레이아웃

• Python 3.11 이상을 대상으로 합니다. 더 최신 버전을 대상으로 하는 저장소를 존중합니다.
• 정방향 호환성을 개선하거나 어노테이션 순서 문제를 해결할 때 from __future__ import annotations를 사용하세요. 필요하지 않은 파일에 기계적으로 추가하지 마십시오.
• 새로운 배포 가능 패키지에는 src/ 레이아웃을 선호합니다.
• 프로젝트 메타데이터와 지원되는 도구 구성은 pyproject.toml에 유지하세요.
• 환경, 의존성 해결, 잠금, 명령 실행에는 uv를 사용하세요.

지원되는 도구 체인

목적	기본값	필수 사용처
포맷 및 린트	Ruff	모든 유지보수 프로젝트
타입 검사	mypy strict	프로덕션 패키지 및 공개 API
테스트 및 커버리지	pytest, pytest-cov, coverage.py	모든 동작 변경
보안 린트	Ruff S 규칙 및 Bandit	프로덕션 패키지
SAST	저장소 규칙이 적용된 Semgrep	유지보수 제품의 CI
의존성 감사	pip-audit	CI 및 릴리스 검사
구조적 로깅	structlog	애플리케이션 및 서비스
추적	OpenTelemetry	네트워크 서비스 및 추적 파이프라인
패키지 관리	uv	모든 프로젝트
Git 훅	pre-commit	유지보수 저장소
시크릿 전달	조직 기본값 Infisical	시크릿을 사용하는 워크로드

승인된 아키텍처 결정은 동등한 공급업체를 선택하거나 소규모 로컬 라이브러리나 스크립트에 맞지 않는 운영 도구를 생략할 수 있습니다. Ruff, 타입 검사, 테스트, 안전한 의존성 처리는 기본 기준으로 유지됩니다.

모델 기반 취약점 스캐너나 AI 리뷰어를 포함한 실험적 도구는 권고 사항입니다. 팀이 지원되는 버전, 명령, 실패 정책, 소유자를 정의하기 전까지 필수 게이트가 되어서는 안 됩니다.

의존성 및 버전 정책

• pyproject.toml에 호환되는 런타임 범위를 선언하세요.
• 애플리케이션과 재현 가능한 개발 환경을 위해 uv.lock을 커밋하세요. 잠금 파일이 정확한 해결된 버전을 소유합니다.
• 배포된 라이브러리의 경우, 정직한 하한을 선언하고 지원되는 Python 버전과 중요한 하한을 테스트하며, 잠금 파일을 소비자 계약으로 의존하지 마세요.
• 품질 및 테스트 도구는 명명된 의존성 그룹에 배치하세요.
• 잠긴 uv 환경을 통해 품질 명령을 실행하세요. pre-commit에서 두 번째 Python 도구 버전 세트를 유지하지 마세요.
• uv lock --upgrade-package <이름> 또는 검토된 전체 잠금 갱신을 통해 의도적으로 업그레이드하세요.

uv 프로젝트의 표준 의존성 감사:

requirements_file="$(mktemp)"
trap 'rm -f "$requirements_file"' EXIT
uv export \
  --frozen \
  --no-dev \
  --no-emit-project \
  --no-hashes \
  --format requirements.txt \
  --output-file "$requirements_file"
uv run --frozen pip-audit \
  --strict \
  --no-deps \
  --requirement "$requirements_file"

내보내기는 pip-audit이 두 번째 그래프를 해결하도록 요청하지 않고 정확히 잠긴 런타임 의존성을 감사합니다. 현재 pip-audit --locked 프로젝트 발견은 pyproject.toml과 pylock.*.toml을 지원하며 uv.lock은 지원하지 않으므로, uv 감사로 pip-audit --locked .를 사용하지 마세요.

pip-audit는 품질 의존성 그룹에 있어야 합니다. 취약점 면제는 권고 ID, 영향 범위, 보완 통제, 소유자(알고 있는 경우), 만료 또는 검토 날짜를 명시해야 합니다.

표준 품질 명령

패키지 경로를 저장소에 맞게 조정하되, 로컬 사용과 CI를 위한 단일 명령 소스를 유지하세요:

uv sync --frozen
uv run --frozen ruff check .
uv run --frozen ruff format --check .
uv run --frozen mypy <패키지-루트>
uv run --frozen bandit -c pyproject.toml -r <패키지-루트>
uv run --frozen semgrep scan --config .semgrep.yml <패키지-루트>
uv run --frozen pytest
# 표준 내보내기 잠금 의존성 감사를 위에서 실행하세요.

CI는 명령과 결과를 기록합니다. 도구나 구성이 없으면 unavailable로 처리하며, 통과로 간주하지 않습니다.

Pre-commit 소유권

비Python 위생 훅은 릴리스별로 고정하세요. Python 품질 도구는 uv run --frozen을 통해 로컬 훅으로 호출하여 로컬 훅과 CI가 uv.lock의 정확한 버전을 사용하도록 하세요.

repos:
  - repo: local
    hooks:
      - id: ruff-check
        name: ruff check
        entry: uv run --frozen ruff check --fix
        language: system
        types_or: [python, pyi]
      - id: ruff-format
        name: ruff format
        entry: uv run --frozen ruff format
        language: system
        types_or: [python, pyi]
      - id: mypy
        name: mypy
        entry: uv run --frozen mypy
        language: system
        pass_filenames: false
        args: [<패키지-루트>]

Bandit, Semgrep, 테스트, 의존성 감사는 CI에서 실행하세요. 지연 시간과 의존성이 저장소에 적합한 경우에만 pre-commit에 추가하세요.

최소 pyproject.toml 결정

플레이스홀더를 복사하지 말고 저장소 패키지 이름과 루트를 사용하세요.

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "B", "S", "UP", "C4", "SIM", "RUF", "D"]
ignore = ["E501"]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true
ignore_missing_imports = false

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra --strict-markers --tb=short --import-mode=importlib"

[tool.coverage.run]
branch = true
source_pkgs = ["your_package"]

[tool.coverage.report]
fail_under = 80
show_missing = true

[tool.bandit]
exclude_dirs = ["tests"]
skips = ["B101"]

모든 무시 항목은 좁은 범위와 이유를 문서화하세요. 전역 무시보다 파일별 무시를 선호하세요.

구조적 로그 계약

애플리케이션은 다음 필드를 내보냅니다. 라이브러리는 호스트 애플리케이션의 로깅 퍼사드를 사용할 수 있으며, 임포트 시 전역 핸들러를 구성해서는 안 됩니다.

필드	요구사항	의미
timestamp	항상	ISO 8601 UTC
level	항상	DEBUG, INFO, WARNING, ERROR, 또는 CRITICAL
event	항상	안정적인 snake-case 이벤트 이름
service	애플리케이션의 경우 항상	서비스 또는 애플리케이션 이름
trace_id	트레이스가 존재할 때	OpenTelemetry 트레이스 ID
span_id	스팬이 존재할 때	OpenTelemetry 스팬 ID
error	실패 시	안전한 예외 유형 및 메시지
duration_ms	측정된 작업 시	경과 시간(밀리초)

Structlog 레벨 프로세서는 일반적으로 소문자 메서드 이름을 받습니다. 레벨을 추가한 후 정규화하세요:

from typing import Any

import structlog


def uppercase_log_level(
    _logger: Any,
    _method_name: str,
    event_dict: dict[str, Any],
) -> dict[str, Any]:
    """구조적 로그 레벨을 공유 스키마로 정규화합니다."""
    level = event_dict.get("level")
    if isinstance(level, str):
        event_dict["level"] = level.upper()
    return event_dict


processors = [
    structlog.processors.add_log_level,
    uppercase_log_level,
    structlog.processors.TimeStamper(fmt="iso", utc=True),
]

프로세서를 단독으로 테스트하는 것이 아니라 최종 렌더링된 이벤트를 테스트하세요.

보안 기준

절대 하지 말아야 할 것:

• 자격 증명, 토큰, 개인 키, 실제 시크릿 값을 커밋하거나 하드코딩
• 실제 시크릿을 .env 또는 TOML 파일에 저장
• 시크릿, 액세스 토큰, 민감한 개인 데이터, 제한되지 않은 요청 본문을 로깅
• 외부 값을 SQL에 직접 삽입
• 외부 또는 변수 입력과 함께 shell=True 사용
• 신뢰할 수 없는 pickle 데이터 역직렬화
• eval, exec, 또는 compile로 신뢰할 수 없는 입력 실행
• 변경 가능한 기본 인수 사용
• 문서화된 공개 재내보내기를 제외한 와일드카드 임포트 사용
• 보안에 민감한 반환값이나 예외를 자동으로 무시
• 빈 except: 사용

Exception은 프로세스, 워커, 태스크, 또는 프레임워크 경계에서만 잡아 핸들러가 안전하게 로그를 남기고 재발생시키거나, 실패를 종료 상태로 매핑하거나, 정의된 프로토콜 오류를 반환하도록 하세요. 애플리케이션 로직 내에서는 특정 예외를 잡으세요.

일반 설정과 시크릿 참조는 설정 파일에 저장하세요. 시크릿 값은 시작 시 Infisical 주입 또는 승인된 동등 방법을 통해 전달하세요. 작업을 수락하기 전에 필수 설정을 검증하세요.