### Install Build Dependencies

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Installs only the build dependencies for the project. This is the first step in an editable install workflow on a fresh virtual environment.

```bash
uv sync --only-group build --no-install-project -p 3.13
```

--------------------------------

### Install Test Dependencies

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Synchronize and install test dependencies without building the project, specifying Python version.

```bash
uv sync --only-group test --no-install-project -p 3.13
```

--------------------------------

### Non-Editable (Release-Style) Install

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Performs a non-editable installation, producing a release build without debug symbols and with optimizations. It requires build dependencies to be installed beforehand.

```bash
uv sync --no-build-isolation --no-editable -v --reinstall -p 3.13
```

--------------------------------

### Install Build Dependencies and Build Extension

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Essential steps to build the duckdb-python extension. Step 1 installs build dependencies, and Step 2 compiles the C++ extension. A full build is required before running tests or scripts.

```bash
# Step 1: install build deps (~5 seconds)
uv sync --only-group build --no-install-project -p 3.13

# Step 2: build the extension (3–10 min cold, ~30s with sccache, use timeout: 600000)
uv sync --no-build-isolation -v --reinstall -p 3.13
```

--------------------------------

### Install DuckDB via pip

Source: https://github.com/duckdb/duckdb-python/blob/main/README.md

Use these commands to install the DuckDB package from PyPI.

```bash
pip install duckdb
```

```bash
pip install 'duckdb[all]'
```

--------------------------------

### Build Extension with Editable Install

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Builds the extension and performs an editable install without build isolation. This allows for fast incremental rebuilds and keeps pybind11 headers accessible to C++ IDEs.

```bash
uv sync --no-build-isolation -v --reinstall -p 3.13
```

--------------------------------

### Quick DuckDB Python Interpreter Check

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Verify DuckDB installation and version, and run a simple SQL query directly from the Python interpreter.

```bash
.venv/bin/python -c 'import duckdb; print(duckdb.__version__); duckdb.sql("SELECT 42").show()'
```

--------------------------------

### Create and Sync Feature Worktree

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Sets up a git worktree for a new feature branch, initializes submodules, and synchronizes dependencies using uv. Recommended for parallel development.

```bash
git worktree add -b feature/my-feature ../feature_my_feature v1.5-variegata
cd ../feature_my_feature
git submodule update --init --recursive
uv sync --only-group build --no-install-project -p 3.13
uv sync --no-build-isolation -v --reinstall -p 3.13
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Execute all pre-commit hooks across the entire project. Hooks are configured in .pre-commit-config.yaml.

```bash
uvx pre-commit run --all-files
```

--------------------------------

### Select Python Version for Sync

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Specifies the Python version to use for the `uv sync` command. Supported versions include 3.10 through 3.14. Do not use free-threaded variants.

```bash
uv sync --no-build-isolation -v --reinstall -p 3.11
```

```bash
uv sync --no-build-isolation -v --reinstall -p 3.14
```

--------------------------------

### Clean Build Artifacts and Environment

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Removes build directories, the virtual environment, the uv lock file, and cleans the uv cache. This provides a clean slate for rebuilding.

```bash
rm -rf build .venv uv.lock && uv cache clean --force
```

--------------------------------

### Build Source Distribution (sdist)

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Builds a source distribution (sdist) for the DuckDB Python extension. The sdist includes the DuckDB submodule source.

```bash
uv build --sdist
```

--------------------------------

### Build Wheel Package

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Builds a wheel package for the DuckDB Python extension. This command is typically used in CI environments.

```bash
uv build --wheel
```

--------------------------------

### Execute DuckDB in Pyodide via HTML

Source: https://github.com/duckdb/duckdb-python/blob/main/pyodide.md

Loads the DuckDB package into a Pyodide environment and executes a SQL query on a local CSV file.

```html
<html>
  <head>
    <meta charset="utf-8" />
  </head>
  <body>
    <script type="text/javascript" src="https://cdn.jsdelivr.net/pyodide/v0.25.1/full/pyodide.js"></script>
    <script type="text/javascript">
      async function main() {
        let pyodide = await loadPyodide();
        await pyodide.loadPackage("micropip");
        const micropip = pyodide.pyimport("micropip");
        await micropip.install(["https://pyodide.duckdb.org/duckdb-0.10.2.dev479-cp311-cp311-emscripten_3_1_46_wasm32.whl"]);
        await pyodide.runPython(`
import duckdb

data = """\
a,b,c
1,2,3
4,5,6
7,8,9"""

with open('data.csv', mode="w") as f:
    f.write(data)

print(duckdb.sql("SELECT COUNT(*) FROM 'data.csv'"))
      `);
      }
      main();
    </script>
  </body>
</html>
```

--------------------------------

### Run One Subsystem's Fast Tests

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Execute fast tests for a specific subsystem, such as arrow integration.

```bash
# Run one subsystem's fast tests
uv run pytest tests/fast/arrow/ -v
```

--------------------------------

### Run Ruff for Linting and Formatting

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Execute Ruff for checking Python code style and formatting. Assumes ruff is configured in pyproject.toml with a 120-character line length and Google docstrings.

```bash
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```

--------------------------------

### Checkout and Create Pull Requests

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Commands to checkout a specific pull request or create a new pull request targeting a specified branch using the GitHub CLI.

```bash
gh pr checkout 167
gh pr create -B v1.5-variegata
```

--------------------------------

### Configure DuckDB Python pybind11 library

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/pybind11/CMakeLists.txt

Defines the object library for the Python wrapper and links necessary dependencies.

```cmake
add_library(python_pybind11 OBJECT pybind_wrapper.cpp)

target_link_libraries(python_pybind11 PRIVATE _duckdb_dependencies)
```

--------------------------------

### DuckDB Python Test Directory Structure

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Overview of the test directory layout, separating fast and slow tests by subsystem.

```text
tests/
├── fast/              # quick per-subsystem tests (seconds each)
│   ├── arrow/         # pyarrow integration
│   ├── pandas/        # pandas integration
│   ├── polars/        # polars integration
│   ├── spark/         # pyspark compatibility
│   ├── adbc/          # ADBC driver
│   ├── api/           # relational API
│   ├── dbapi/         # PEP 249 DB-API 2.0
│   ├── capi/          # C API bindings
│   ├── udf/           # Python UDFs
│   └── ...
└── slow/              # heavy integration/performance tests
```

--------------------------------

### Memory Profiling with Memray

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Profile Python script memory usage using Memray. Generates a binary profile file and then creates a flamegraph visualization.

```bash
.venv/bin/python -m memray run -o profile.bin repro.py
.venv/bin/python -m memray flamegraph profile.bin
open memray-flamegraph-profile.html
```

--------------------------------

### Configure sccache for C++ Compilation

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Sets environment variables to use sccache as a compiler launcher for C and C++ builds. This significantly speeds up compilation by caching object files.

```bash
# Export before any uv sync
export CMAKE_C_COMPILER_LAUNCHER="$(command -v sccache)"
export CMAKE_CXX_COMPILER_LAUNCHER="$(command -v sccache)"
```

--------------------------------

### Run Slow Integration Tests

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Execute slow integration tests, which may require significant time and resources.

```bash
# Slow tests (be patient)
uv run pytest -n 4 -r skip -vv tests/slow/test_h2oai_arrow.py
```

--------------------------------

### Run a Specific Test by Name

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Execute a single test case identified by its name within a specific test file.

```bash
# Run a specific test by name
uv run pytest tests/fast/api/test_relation.py -k 'test_value_relation' -v
```

--------------------------------

### Download CI Artifacts

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Downloads artifacts from a specific GitHub Actions run. Use the run ID obtained from `gh run list`.

```bash
gh run download <run-id> -D ./artifacts/
```

--------------------------------

### Configure DuckDB Python Native Library with CMake

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/native/CMakeLists.txt

Defines the python_native object library and links necessary dependencies for the DuckDB Python extension.

```cmake
add_library(python_native OBJECT python_objects.cpp python_conversion.cpp)

target_link_libraries(python_native PRIVATE _duckdb_dependencies)
```

--------------------------------

### Trigger Incremental C++ Rebuild

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Triggers an incremental rebuild of the C++ extensions by touching the __init__.py file. This is the fastest way to pick up C++ source changes after editing.

```bash
# Fastest: touch the __init__.py to trigger scikit-build-core's rebuild detection
touch duckdb/__init__.py && uv sync --no-build-isolation -v --reinstall
```

--------------------------------

### Update Git Submodules

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Ensures the DuckDB engine submodule is initialized and up-to-date. Run this after creating a worktree or switching branches.

```bash
git submodule update --init --recursive
```

--------------------------------

### Run Mypy for Type Checking

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Perform static type checking using Mypy in strict mode. Configuration is detailed in the [tool.mypy] section of pyproject.toml.

```bash
uv run mypy
```

--------------------------------

### Inspect macOS Deployment Target

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Retrieve the MACOSX_DEPLOYMENT_TARGET value used by Python's sysconfig. This is useful for ensuring compatibility across different macOS versions.

```bash
.venv/bin/python -c "import sysconfig; print(sysconfig.get_config_var('MACOSX_DEPLOYMENT_TARGET'))"
```

--------------------------------

### Parallel Test Execution with Pytest-xdist

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Utilize pytest-xdist for parallel test execution across multiple CPU cores.

```bash
# Parallel execution (pytest-xdist)
uv run pytest tests/fast/ -n auto -r skip -vv
```

--------------------------------

### Configure DuckDB Python Relation Library

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/pyrelation/CMakeLists.txt

Defines the object library for Python relations and links the necessary internal dependencies.

```cmake
add_library(python_relation OBJECT initialize.cpp)

target_link_libraries(python_relation PRIVATE _duckdb_dependencies)
```

--------------------------------

### AddressSanitizer Debugging on macOS

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Run Python scripts with AddressSanitizer enabled to detect memory errors. This requires Xcode's toolchain and is specific to macOS.

```bash
DYLD_INSERT_LIBRARIES=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/17/lib/darwin/libclang_rt.asan_osx_dynamic.dylib \
    .venv/bin/python repro.py
```

--------------------------------

### Timezone Isolation for Testing

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Run Python code with a deliberately non-existent timezone set to test timezone-related behavior in isolation.

```bash
TZ=not/existing .venv/bin/python -c 'import duckdb; ...'
```

--------------------------------

### List Recent CI Runs

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Fetches a list of recent CI runs for the DuckDB-Python repository or a specific workflow. Useful for monitoring build status.

```bash
gh run list --repo duckdb/duckdb-python --workflow="Packaging" --limit 5
gh run list --workflow pypi_packaging.yml --json status,url -s failure
```

--------------------------------

### Link Python Connection Library to DuckDB Dependencies

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/pyconnection/CMakeLists.txt

Links the 'python_connection' target to the private DuckDB dependencies. This ensures that the necessary DuckDB libraries are available during the build process for the Python connection.

```cmake
target_link_libraries(python_connection PRIVATE _duckdb_dependencies)
```

--------------------------------

### Link DuckDB Dependencies to Python Expression Library

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/pyexpression/CMakeLists.txt

Links the 'python_expression' target to the '_duckdb_dependencies'. This ensures that the necessary DuckDB internal libraries are available when building the Python expression component.

```cmake
target_link_libraries(python_expression PRIVATE _duckdb_dependencies)
```

--------------------------------

### Reinstall Only DuckDB Package

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Reinstalls only the DuckDB package without affecting other dependencies. This is useful when the dependency lock file has not changed.

```bash
uv sync --reinstall-package duckdb
```

--------------------------------

### Add Python Jupyter Library

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/jupyter/CMakeLists.txt

Configures a CMake library for Python Jupyter integration, compiling the specified C++ source file.

```cmake
add_library(python_jupyter OBJECT jupyter_progress_bar_display.cpp)
```

--------------------------------

### Add Python Expression Library for Clang-Tidy

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/pyexpression/CMakeLists.txt

Configures a CMake library target named 'python_expression' as an object library, compiling 'initialize.cpp'. This is specifically for use with clang-tidy checks.

```cmake
add_library(python_expression OBJECT initialize.cpp)
```

--------------------------------

### Filter Tests by Markers

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Execute tests that match specific markers, excluding others based on defined criteria.

```bash
# Filter by markers
uv run pytest tests/fast/ -r skip -vv -m "not (performance and threading)"
```

--------------------------------

### Python Memory Debug Allocator

Source: https://github.com/duckdb/duckdb-python/blob/main/CLAUDE.md

Run a Python script using the debug memory allocator to help identify memory allocation issues.

```bash
PYTHONMALLOC=malloc_debug .venv/bin/python repro.py
```

--------------------------------

### Define DuckDB Python common library in CMake

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/common/CMakeLists.txt

Configures the python_common object library and links it against required DuckDB dependencies.

```cmake
add_library(python_common OBJECT exceptions.cpp)

target_link_libraries(python_common PRIVATE _duckdb_dependencies)
```

--------------------------------

### Add Python Connection Library Target

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/pyconnection/CMakeLists.txt

Defines a CMake library target named 'python_connection' as an OBJECT library, compiling the 'type_creation.cpp' source file. This is typically used for internal build steps.

```cmake
add_library(python_connection OBJECT type_creation.cpp)
```

--------------------------------

### Link Python Jupyter Library

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/jupyter/CMakeLists.txt

Links the Python Jupyter library against DuckDB's internal dependencies. Ensure _duckdb_dependencies is correctly defined in your build system.

```cmake
target_link_libraries(python_jupyter PRIVATE _duckdb_dependencies)
```

--------------------------------

### Link Python Functional Library Dependencies

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/functional/CMakeLists.txt

Links the Python functional library target against DuckDB's internal dependencies. Ensure _duckdb_dependencies is correctly defined.

```cmake
target_link_libraries(python_functional PRIVATE _duckdb_dependencies)
```

--------------------------------

### Define Python Arrow Library

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/arrow/CMakeLists.txt

Defines the C++ object library for the Python Arrow integration. This is used for clang-tidy checks.

```cmake
add_library(
  python_arrow OBJECT
  arrow_array_stream.cpp arrow_export_utils.cpp filter_pushdown_visitor.cpp
  polars_filter_pushdown.cpp pyarrow_filter_pushdown.cpp)

target_link_libraries(python_arrow PRIVATE _duckdb_dependencies)
```

--------------------------------

### Add Python NumPy Library Target

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/numpy/CMakeLists.txt

Defines a CMake library target for the Python NumPy integration. This includes compiling several C++ source files related to NumPy handling within DuckDB.

```cmake
add_library(
  python_numpy OBJECT
  type.cpp numpy_scan.cpp array_wrapper.cpp raw_array_wrapper.cpp
  numpy_bind.cpp numpy_result_conversion.cpp)

target_link_libraries(python_numpy PRIVATE _duckdb_dependencies)
```

--------------------------------

### Add Python Functional Library Target

Source: https://github.com/duckdb/duckdb-python/blob/main/src/duckdb_py/functional/CMakeLists.txt

Defines a CMake library target for the Python functional component. This is typically used for clang-tidy checks.

```cmake
add_library(python_functional OBJECT functional.cpp)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.