Skip to main content

Python

The Goose Python package has its own repository at kumose/goose-python and uses pybind11 to create Python bindings with Goose.

Prerequisites​

This guide assumes:

  1. You have a working copy of the Goose Python package source (including git submodules and tags)
  2. You have Astral UV version >= 0.8.0 installed
  3. You run commands from the root of the goose-python source

We are opinionated about using Astral UV for Python environment and dependency management. While using pip for a development environment with an editable install without build isolation is possible, we don't provide guidance for that approach in this guide.

We use CLion as our IDE. This guide doesn't include specific instructions for other IDEs, but the setup should be similar.

1. Goose Python Repository​

Start by forking goose-python into a personal repository, then clone your fork:

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

If you've already cloned without submodules:

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

Important notes:

  • Goose is vendored as a git submodule and must be initialized
  • Goose version determination depends on local availability of git tags
  • If switching between branches with different submodule refs, add the git hooks:
git config --local core.hooksPath .githooks/

2. Install Astral uv​

Install uv version >= 0.8.0.

Development Environment Setup​

1. Platform-Specific Setup​

All Platforms:

  • Python 3.9+ supported
  • uv >= 0.8.0 required
  • CMake and Ninja (installed via UV)
  • C++ compiler toolchain

Linux (Ubuntu 24.04):

sudo apt-get update
sudo apt-get install ccache

macOS:

# Xcode command line tools
xcode-select --install

Windows:

  • Visual Studio 2019+ with C++ support
  • Git for Windows

2. Install Dependencies and Build​

Set up the development environment in two steps:

# Install all development dependencies without building the project
uv sync --no-install-project

# Build and install the project without build isolation
uv sync --no-build-isolation

Why two steps?

  • uv sync performs editable installs by default with scikit-build-core using a persistent build-dir
  • The build happens in an isolated, ephemeral environment where cmake's paths point to non-existing directories
  • Installing dependencies first, then building without isolation ensures proper cmake integration

3. Enable Pre-Commit Hooks​

We run a number of linting, formatting and type-checking in CI. You can run all of these manually, but to make your life easier you can install the exact same checks we run in CI as git hooks with pre-commit, which is already installed as part of the dev dependencies:

uvx pre-commit install

This will run all required checks before letting your commit pass.

You can also install a post-checkout hook that always runs git submodule update --init --recursive. When you change branches between main and a bugfix branch, this makes sure the goose submodule is always correctly initialized:

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

4. Verify Installation​

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

Development Workflow​

Running Tests​

Run all tests:

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

Run fast tests only (excludes slow directory):

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

Test Coverage​

Run with coverage (compiles extension with --coverage for C++ coverage):

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

Check Python coverage:

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

Check C++ coverage:

uv run gcovr \
  --gcov-ignore-errors all \
  --root "$PWD" \
  --filter "${PWD}/src/goose_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/goose_py \
  --print-summary

Building Wheels​

Build wheel for your system:

uv build

Build for specific Python version:

uv build -p 3.9

Cleaning Build Artifacts​

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

IDE Setup (CLion)​

For CLion users, the project can be configured for C++ debugging of the Python extension:

CMake Profile Configuration​

In Settings → Build, Execution, Deployment → CMake, create a Debug profile:

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

Python Debug Configuration​

Create a CMake Application run configuration:

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

This allows setting C++ breakpoints and debugging Python scripts that use the Goose extension.

Debugging​

Command Line Debugging​

Set breakpoints and debug with lldb:

# Example Python script (test.py)
# import goose
# print(goose.sql("select * from range(1000)").df())

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

In lldb:

# Set breakpoint (library loads when imported)
(lldb) br s -n goose::GoosePyRelation::FetchDF
(lldb) r

Cross-Platform Testing​

You can run the packaging workflow manually on your fork for any branch, choosing platforms and test suites via the GitHub Actions web interface.

Troubleshooting​

Build Issues​

Missing git tags: If you forked Goose Python, ensure you have the upstream tags:

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

Platform-Specific Issues​

Windows compilation: Ensure you have Visual Studio 2019+ with C++ support installed.