UV Workspaces를 사용한 파이썬 모노레포 관리

3 hours ago 1

UV Workspaces를 사용한 파이썬 모노레포 관리 요약

이 영상은 단일 깃(Git) 레포지토리에서 여러 개의 파이썬 애플리케이션(모노레포)을 관리할 때 발생하는 문제점들을 UV Workspaces 기능을 사용하여 깔끔하게 해결하는 방법을 소개합니다.

1. 영상 요약

문제점

하나의 레포지토리에서 CLI 도구와 FastAPI 앱을 동시에 개발할 때, 다음과 같은 문제들이 발생합니다.

코드 중복: CLI와 API에서 공통으로 사용하는 기능(예: 헤드라인 크롤링 함수)을 복사/붙여넣기 해야 합니다.
복잡한 환경 관리: 각 앱마다 별도의 가상 환경을 관리해야 하므로, 의존성 버전이 충돌하거나 디스크 공간이 낭비됩니다.

해결책: UV Workspaces

UV Workspaces는 이러한 문제들을 해결하기 위해 두 가지 핵심 기능을 제공합니다.

공유 의존성 및 단일 가상 환경
- 프로젝트 루트(최상위)에 있는 pyproject.toml 파일에서 공통 의존성을 정의할 수 있습니다.
- uv sync 명령어를 실행하면, UV가 이 설정 파일을 읽어 레포지토리 전체에서 공유하는 단일 가상 환경(.venv)을 루트 폴더에 생성합니다.
- 이를 통해 모든 하위 프로젝트(CLI, API 등)가 동일한 환경과 의존성을 공유하게 되어 버전 충돌을 방지하고 관리가 용이해집니다.
내부 패키지를 통한 코드 공유
- 중복되는 공통 코드(예: fetch_headlines 함수)를 core와 같은 별도의 "내부 패키지"로 분리할 수 있습니다.
- 워크스페이스 설정을 통해 이 core 패키지를 PyPI가 아닌 로컬 소스로 인식시킵니다.
- 이제 CLI 앱과 API 앱에서 from core.news import fetch_headlines와 같이 이 공통 코드를 import하여 재사용할 수 있습니다.

2. UV Workspaces 사용 방법

1단계: 워크스페이스 설정

프로젝트 루트 폴더에 pyproject.toml 파일을 만들고, [tool.uv.workspace] 섹션을 정의하여 하위 프로젝트들이 어디에 있는지 알려줍니다.

[tool.uv.workspace] # "packages" 폴더 내의 모든 하위 폴더를 워크스페이스 멤버로 인식 members = ["packages/*"]

2단계: 의존성 관리

공유 의존성: 모든 프로젝트가 공통으로 쓰는 의존성(예: python-dotenv)은 **루트 pyproject.toml**에 추가합니다.
개별 의존성: 특정 앱(예: api)에서만 사용하는 의존성(예: fastapi, uvicorn)은 해당 앱의 pyproject.toml (예: packages/api/pyproject.toml)에 추가합니다.
루트 폴더에서 uv sync를 실행하면, UV가 모든 pyproject.toml을 스캔하여 루트 가상 환경에 필요한 모든 의존성을 설치합니다.

3단계: 내부 패키지로 코드 공유

packages/core와 같이 공유 코드를 담을 새 패키지(폴더)를 만듭니다.
**루트 pyproject.toml**에 이 패키지를 일반 의존성처럼 추가합니다.
**루트 pyproject.toml**에 [tool.uv.sources] 섹션을 추가하여, core 패키지를 PyPI가 아닌 워크스페이스 내부에서 찾도록 설정합니다.

[project] # 1. 내부 패키지를 의존성으로 추가 dependencies = [ "core", "python-dotenv" ] # 2. 'core'가 로컬 워크스페이스 패키지임을 명시 [tool.uv.sources] core = { workspace = true }