Python

Python (Python 클라이언트 빌드)

DuckDB Python 패키지는 자체 저장소인 duckdb/duckdb-python을 가지고 있고, pybind11을 사용해 DuckDB와의 Python 바인딩을 만들어요.

출처: 문서

본문

사전 요구 사항 (Prerequisites)

이 가이드는 다음을 가정해요:

  1. DuckDB Python 패키지 소스의 작업 복사본(서브모듈과 태그 포함)이 있다.
  2. Astral UV 버전 >= 0.8.0이 설치되어 있다.
  3. duckdb-python 소스의 루트에서 명령을 실행한다.

Python 환경과 의존성 관리를 위해 Astral UV 사용을 선호해요. 빌드 격리 없이 편집 가능한 설치로 개발 환경에 pip을 사용하는 것도 가능하지만, 이 가이드에서는 그 접근 방식을 다루지 않아요.

우리는 CLion을 IDE로 사용해요. 이 가이드는 다른 IDE에 대한 구체적인 지침을 포함하지 않지만, 설정은 유사해야 해요.

1. DuckDB Python 저장소

먼저 duckdb-python을 포크해 개인 저장소로 만든 다음, 포크를 클론해요:

git clone --recurse-submodules YOUR_FORK_URL
cd duckdb-python
git remote add upstream https://github.com/duckdb/duckdb-python.git
git fetch --all

서브모듈 없이 이미 클론했다면:

git submodule update --init --recursive
git remote add upstream https://github.com/duckdb/duckdb-python.git
git fetch --all

중요한 참고 사항:

  • DuckDB는 git 서브모듈로 벤더링되며 초기화되어야 해요
  • DuckDB 버전 결정은 로컬 git 태그 사용 가능 여부에 달려 있어요
  • 서브모듈 ref가 다른 브랜치를 전환할 때 git 훅을 추가해요:
git config --local core.hooksPath .githooks/

2. Astral uv 설치

버전 >= 0.8.0의 uv를 설치해요.

개발 환경 설정 (Development Environment Setup)

1. 플랫폼별 설정

모든 플랫폼

  • Python 3.9+ 지원
  • uv >= 0.8.0 필요
  • CMake 및 Ninja (UV로 설치)

Windows

다음이 설치되어 있는지 확인해요:

  • C++ 지원이 있는 Visual Studio 2019+
  • Git for Windows

2. 의존성 설치 및 빌드

개발 환경을 두 단계로 설정해요:

# 프로젝트 빌드 없이 모든 개발 의존성 설치
uv sync --no-install-project

# 빌드 격리 없이 프로젝트 빌드 및 설치
uv sync --no-build-isolation

왜 두 단계인가요?

  • uv sync는 지속적인 build-dir을 가진 scikit-build-core로 기본적으로 편집 가능한 설치를 수행해요
  • 빌드는 cmake의 경로가 존재하지 않는 디렉토리를 가리키는 격리된 임시 환경에서 일어나요
  • 먼저 의존성을 설치한 다음 격리 없이 빌드하면 올바른 cmake 통합이 보장돼요

3. Pre-Commit 훅 활성화

우리는 CI에서 여러 린팅, 포맷팅, 타입 검사를 실행해요. 수동으로 모두 실행할 수도 있지만, 개발 의존성의 일부로 이미 설치된 pre-commit으로 CI에서 실행하는 것과 동일한 검사를 git 훅으로 설치할 수 있어요:

uvx pre-commit install

이렇게 하면 커밋이 통과되기 전에 모든 필요한 검사가 실행돼요.

또한 항상 git submodule update --init --recursive를 실행하는 post-checkout 훅을 설치할 수도 있어요. main과 버그픽스 브랜치 사이를 전환할 때 duckdb 서브모듈이 항상 올바르게 초기화되도록 보장해요:

uvx pre-commit install --hook-type post-checkout

4. 설치 검증

uv run python -c "import duckdb; print(duckdb.sql('SELECT 42').fetchall())"

개발 워크플로 (Development Workflow)

테스트 실행

모든 테스트를 실행:

uv run --no-build-isolation pytest ./tests --verbose

빠른 테스트만 실행 (slow 디렉토리 제외):

uv run --no-build-isolation pytest ./tests --verbose --ignore=./tests/slow

테스트 커버리지

커버리지로 실행 (--coverage로 C++ 커버리지용 확장 컴파일):

COVERAGE=1 uv run --no-build-isolation coverage run -m pytest ./tests --verbose

Python 커버리지 확인:

uv run coverage html -d htmlcov-python
uv run coverage report --format=markdown

C++ 커버리지 확인:

uv run gcovr \
  --gcov-ignore-errors all \
  --root "$PWD" \
  --filter "${PWD}/src/duckdb_py" \
  --exclude '.*/\.cache/.*' \
  --gcov-exclude '.*/\.cache/.*' \
  --gcov-exclude '.*/external/.*' \
  --gcov-exclude '.*/site-packages/.*' \
  --exclude-unreachable-branches \
  --exclude-throw-branches \
  --html --html-details -o coverage-cpp.html \
  build/coverage/src/duckdb_py \
  --print-summary

휠 빌드

시스템용 휠 빌드:

uv build

특정 Python 버전용 빌드:

uv build -p 3.9

휠을 설치하려면:

uv pip install dist/duckdb-*.whl

빌드 산출물 정리

uv cache clean
rm -rf build .venv uv.lock

IDE 설정 (CLion)

CLion 사용자를 위해, 이 프로젝트는 Python 확장의 C++ 디버깅용으로 구성할 수 있어요:

CMake 프로파일 구성

Settings → Build, Execution, Deployment → CMake에서 Debug 프로파일을 만들어요:

  • Name: Debug
  • Build type: Debug
  • Generator: Ninja
  • CMake Options: 
    -DCMAKE_PREFIX_PATH=$CMakeProjectDir$/.venv;$CMAKE_PREFIX_PATH

Python 디버그 구성

CMake Application 실행 구성을 만들어요:

  • Name: Python Debug
  • Target: All targets
  • Executable: ⟨PROJECT_DIR⟩/.venv/bin/python3
  • Program arguments: $FilePath$
  • Working directory: $ProjectFileDir$

이렇게 하면 C++ 중단점을 설정하고 DuckDB 확장을 사용하는 Python 스크립트를 디버깅할 수 있어요.

디버깅 (Debugging)

커맨드라인 디버깅

lldb로 중단점을 설정하고 디버깅해요:

# 예제 Python 스크립트 (test.py)
# import duckdb
# print(duckdb.sql("select * from range(1000)").df())

lldb -- .venv/bin/python3 test.py

lldb에서:

# 중단점 설정 (라이브러리는 import 시 로드됨)
(lldb) br s -n duckdb::DuckDBPyRelation::FetchDF
(lldb) r

크로스 플랫폼 테스트

GitHub Actions 웹 인터페이스를 통해 플랫폼과 테스트 스위트를 선택해, 포크에서 어떤 브랜치든 패키징 워크플로를 수동으로 실행할 수 있어요.

문제 해결 (Troubleshooting)

빌드 이슈

누락된 git 태그: DuckDB Python을 포크했다면 업스트림 태그가 있는지 확인해요:

git remote add upstream https://github.com/duckdb/duckdb-python.git
git fetch --tags upstream
git push --tags

더 알아보기 (Learn more)

Python 클라이언트의 사용법은 [Python client]({% link docs/current/clients/python/overview.md %}) 문서를 참고해요.