워크스페이스 메타데이터

개요

uv workspace metadata 명령은 워크스페이스(workspace) 또는 PEP 723 스크립트 정보를 도구 통합용 JSON으로 내보냅니다. 주요 출력은 uv.lock의 정확한 패키지 버전을 포함하는 의존성 그래프가 담긴 resolution 필드입니다.

그래프 구조

의존성 그래프는 다음 다섯 가지 노드 유형으로 구성됩니다.

• script — PEP 723 스크립트와 그 직접 의존성
• workspace — 워크스페이스 루트와 워크스페이스 전용 의존성 그룹
• package — 패키지(package) 자체
• extra — 패키지 엑스트라(extra)를 위한 { "extra": "extraname" } 형식
• group — 의존성 그룹(dependency group)을 위한 { "group": "groupname" } 형식

여러 버전 처리

그래프 내에서 패키지가 여러 버전으로 나타날 수 있는 경우는 두 가지입니다.

1. 플랫폼 충돌 — 플랫폼마다 서로 충돌하는 버전을 요구하는 경우
2. 워크스페이스 충돌 — 일부 워크스페이스 멤버가 상호 배타적인 경우

제공되는 보장은 다음과 같습니다. "마커(marker)를 구체적으로 선택했을 때, 충돌 없는 패키지 집합을 선택하면 결과 설치에 여러 패키지 버전이 포함되지 않습니다."

그래프 분석 권장 방법

전체 해석(resolution) 맵을 순회하여 노드를 찾는 대신, 다음 방법을 권장합니다.

• 자연스러운 진입점(워크스페이스 루트, 워크스페이스 멤버, 스크립트)에서 시작합니다.
• 의존성 엣지(edge)를 재귀적으로 따라갑니다.
• 다른 메타데이터 필드에서 제공하는 노드 ID를 사용합니다.
• 여러 버전을 분석할 때는 conflicts 필드를 참고합니다.

스키마 예시

JSON 출력에는 다음이 포함됩니다.

• schema — 버전 식별자
• workspace_root — uv.lock이 있는 디렉터리
• environment — 환경 경로 (--sync 사용 시)
• script 또는 workspace — 기본 진입점
• requires_python — Python 버전 제약
• members — 워크스페이스 멤버 목록
• conflicts — 상호 배타적 항목
• resolution — 완전한 의존성 그래프 맵

패키지 노드에는 dependencies, optional_dependencies(엑스트라), dependency_groups를 포함한 메타데이터가 담겨 있습니다. 엑스트라는 항상 기본 패키지에 의존하지만, 그룹은 그렇지 않습니다.

원문(영어): https://docs.astral.sh/uv/reference/internals/metadata/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/reference/internals/metadata/