Tasks

Development and documentation tasks for polars-bigquery-client.

Requires Rust (install with rustup), uv, and mask.

For integration and benchmark tests, authenticate with Google Cloud (gcloud auth application-default login) and set the GOOGLE_CLOUD_PROJECT environment variable.

build

Build all sub-projects for development.

set -euo pipefail
$MASK rust-arrow-bigquery build
$MASK py-arrow-bigquery build
$MASK py-polars-bigquery build
$MASK docs build

$ErrorActionPreference = "Stop"
& $env:MASK rust-arrow-bigquery build
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& $env:MASK py-arrow-bigquery build
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& $env:MASK py-polars-bigquery build
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& $env:MASK docs build
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

rust-arrow-bigquery

Commands for the arrow-bigquery Rust crate (crates/arrow-bigquery).

build

Compile the Rust workspace, unit test, and benchmark binaries (crates/arrow-bigquery).

set -euo pipefail
cargo test --workspace --exclude py-arrow-bigquery --exclude py-polars-expressions-testing --lib --bins --benches --features testing --no-run

$ErrorActionPreference = "Stop"
cargo test --workspace --exclude py-arrow-bigquery --exclude py-polars-expressions-testing --lib --bins --benches --features testing --no-run
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

test

Run tests for crates/arrow-bigquery.

unit

Run Rust unit tests (crates/arrow-bigquery), matching .github/workflows/test-rust-unit.yml.

set -euo pipefail
cargo test --workspace --exclude py-arrow-bigquery --exclude py-polars-expressions-testing --lib --bins --features testing

$ErrorActionPreference = "Stop"
cargo test --workspace --exclude py-arrow-bigquery --exclude py-polars-expressions-testing --lib --bins --features testing
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

integration

Run Rust BigQuery integration tests (crates/arrow-bigquery/tests/integration_test.rs). Requires GOOGLE_CLOUD_PROJECT.

set -euo pipefail
: "${GOOGLE_CLOUD_PROJECT:?Set GOOGLE_CLOUD_PROJECT to run BigQuery integration tests}"
cargo test --package arrow-bigquery --test integration_test --features testing

$ErrorActionPreference = "Stop"
if (-not $env:GOOGLE_CLOUD_PROJECT) {
  Write-Error "Set GOOGLE_CLOUD_PROJECT to run BigQuery integration tests"
  exit 1
}
cargo test --package arrow-bigquery --test integration_test --features testing
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

benchmark

Run Rust BigQuery Criterion benchmarks (crates/arrow-bigquery/benches/read.rs). Requires GOOGLE_CLOUD_PROJECT.

OPTIONS * filter * flags: -f --filter * type: string * desc: Only run Criterion benchmarks matching the given regular expression

set -euo pipefail
: "${GOOGLE_CLOUD_PROJECT:?Set GOOGLE_CLOUD_PROJECT to run BigQuery benchmark tests}"
bench_args=()
if [ -n "${filter:-}" ]; then
  bench_args+=("$filter")
fi
cargo bench --package arrow-bigquery --bench read -- "${bench_args[@]}"

$ErrorActionPreference = "Stop"
if (-not $env:GOOGLE_CLOUD_PROJECT) {
  Write-Error "Set GOOGLE_CLOUD_PROJECT to run BigQuery benchmark tests"
  exit 1
}
$benchArgs = @()
if ($env:filter) {
  $benchArgs += $env:filter
}
cargo bench --package arrow-bigquery --bench read -- @benchArgs
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

py-arrow-bigquery

Commands for the arrow-bigquery Python package (py-arrow-bigquery).

build

Build the py-arrow-bigquery Rust extension and install editable dependencies via uv.

OPTIONS * resolution * flags: -r --resolution * type: string * desc: Dependency resolution strategy for uv (highest, lowest, lowest-direct) * upgrade * flags: -U --upgrade * desc: Allow package upgrades, ignoring pinned versions in uv.lock

set -euo pipefail
uv_args=()
if [ -n "${resolution:-}" ]; then
  uv_args+=(--resolution "$resolution")
fi
if [ "${upgrade:-}" = "true" ]; then
  uv_args+=(--upgrade)
fi
uv sync "${uv_args[@]}" --project py-arrow-bigquery --group dev

$ErrorActionPreference = "Stop"
$uvArgs = @()
if ($env:resolution) {
  $uvArgs += @("--resolution", $env:resolution)
}
if ($env:upgrade -eq "true") {
  $uvArgs += "--upgrade"
}
uv sync @uvArgs --project py-arrow-bigquery --group dev
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

test

Run tests for py-arrow-bigquery.

unit

Run py-arrow-bigquery unit tests, matching .github/workflows/test-py-arrow-unit.yml.

OPTIONS * resolution * flags: -r --resolution * type: string * desc: Dependency resolution strategy for uv (highest, lowest, lowest-direct) * upgrade * flags: -U --upgrade * desc: Allow package upgrades, ignoring pinned versions in uv.lock

set -euo pipefail
uv_args=()
if [ -n "${resolution:-}" ]; then
  uv_args+=(--resolution "$resolution")
fi
if [ "${upgrade:-}" = "true" ]; then
  uv_args+=(--upgrade)
fi
uv run "${uv_args[@]}" --project py-arrow-bigquery --group test pytest -n auto py-arrow-bigquery/tests/unit

$ErrorActionPreference = "Stop"
$uvArgs = @()
if ($env:resolution) {
  $uvArgs += @("--resolution", $env:resolution)
}
if ($env:upgrade -eq "true") {
  $uvArgs += "--upgrade"
}
uv run @uvArgs --project py-arrow-bigquery --group test pytest -n auto py-arrow-bigquery/tests/unit
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

integration

Run py-arrow-bigquery integration tests (if present).

set -euo pipefail
echo "No standalone integration tests in py-arrow-bigquery; covered by rust-arrow-bigquery and py-polars-bigquery."

Write-Host "No standalone integration tests in py-arrow-bigquery; covered by rust-arrow-bigquery and py-polars-bigquery."

py-polars-bigquery

Commands for the polars-bigquery Python package (py-polars-bigquery).

build

Sync dependencies and install py-polars-bigquery (and workspace member arrow-bigquery) in editable mode via uv.

OPTIONS * resolution * flags: -r --resolution * type: string * desc: Dependency resolution strategy for uv (highest, lowest, lowest-direct) * upgrade * flags: -U --upgrade * desc: Allow package upgrades, ignoring pinned versions in uv.lock

set -euo pipefail
uv_args=()
if [ -n "${resolution:-}" ]; then
  uv_args+=(--resolution "$resolution")
fi
if [ "${upgrade:-}" = "true" ]; then
  uv_args+=(--upgrade)
fi
uv sync "${uv_args[@]}" --project py-polars-bigquery --group dev

$ErrorActionPreference = "Stop"
$uvArgs = @()
if ($env:resolution) {
  $uvArgs += @("--resolution", $env:resolution)
}
if ($env:upgrade -eq "true") {
  $uvArgs += "--upgrade"
}
uv sync @uvArgs --project py-polars-bigquery --group dev
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

test

Run tests for py-polars-bigquery.

unit

Run py-polars-bigquery unit tests, matching .github/workflows/test-py-polars-unit.yml.

OPTIONS * resolution * flags: -r --resolution * type: string * desc: Dependency resolution strategy for uv (highest, lowest, lowest-direct) * upgrade * flags: -U --upgrade * desc: Allow package upgrades, ignoring pinned versions in uv.lock

set -euo pipefail
uv_args=()
if [ -n "${resolution:-}" ]; then
  uv_args+=(--resolution "$resolution")
fi
if [ "${upgrade:-}" = "true" ]; then
  uv_args+=(--upgrade)
fi
uv run "${uv_args[@]}" --project py-polars-bigquery --group test pytest -n auto py-polars-bigquery/tests/unit

$ErrorActionPreference = "Stop"
$uvArgs = @()
if ($env:resolution) {
  $uvArgs += @("--resolution", $env:resolution)
}
if ($env:upgrade -eq "true") {
  $uvArgs += "--upgrade"
}
uv run @uvArgs --project py-polars-bigquery --group test pytest -n auto py-polars-bigquery/tests/unit
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

integration

Run py-polars-bigquery system/integration tests (py-polars-bigquery/tests/system), matching cloudbuild.yaml. Requires GOOGLE_CLOUD_PROJECT.

set -euo pipefail
: "${GOOGLE_CLOUD_PROJECT:?Set GOOGLE_CLOUD_PROJECT to run BigQuery integration tests}"
uv run --project py-polars-bigquery --group test pytest py-polars-bigquery/tests/system

$ErrorActionPreference = "Stop"
if (-not $env:GOOGLE_CLOUD_PROJECT) {
  Write-Error "Set GOOGLE_CLOUD_PROJECT to run BigQuery integration tests"
  exit 1
}
uv run --project py-polars-bigquery --group test pytest py-polars-bigquery/tests/system
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

benchmark

Run py-polars-bigquery local benchmarks (py-polars-bigquery/tests/benchmark) with pytest-benchmark. Requires GOOGLE_CLOUD_PROJECT.

OPTIONS * output * flags: -o --output * type: string * desc: Write pytest-benchmark results to a JSON file (--benchmark-json)

set -euo pipefail
: "${GOOGLE_CLOUD_PROJECT:?Set GOOGLE_CLOUD_PROJECT to run BigQuery benchmark tests}"
pytest_args=(--benchmark-only)
if [ -n "${output:-}" ]; then
  pytest_args+=(--benchmark-json "$output")
fi
uv run --project py-polars-bigquery --group test pytest "${pytest_args[@]}" py-polars-bigquery/tests/benchmark

$ErrorActionPreference = "Stop"
if (-not $env:GOOGLE_CLOUD_PROJECT) {
  Write-Error "Set GOOGLE_CLOUD_PROJECT to run BigQuery benchmark tests"
  exit 1
}
$pytestArgs = @("--benchmark-only")
if ($env:output) {
  $pytestArgs += @("--benchmark-json", $env:output)
}
uv run --project py-polars-bigquery --group test pytest @pytestArgs py-polars-bigquery/tests/benchmark
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

py-polars-expressions-testing

Commands for the polars-expressions-testing Python package (py-polars-expressions-testing).

build

Build the py-polars-expressions-testing Rust extension and install editable dependencies via uv.

OPTIONS * resolution * flags: -r --resolution * type: string * desc: Dependency resolution strategy for uv (highest, lowest, lowest-direct) * upgrade * flags: -U --upgrade * desc: Allow package upgrades, ignoring pinned versions in uv.lock

set -euo pipefail
uv_args=()
if [ -n "${resolution:-}" ]; then
  uv_args+=(--resolution "$resolution")
fi
if [ "${upgrade:-}" = "true" ]; then
  uv_args+=(--upgrade)
fi
uv sync "${uv_args[@]}" --project py-polars-expressions-testing --group dev

$ErrorActionPreference = "Stop"
$uvArgs = @()
if ($env:resolution) {
  $uvArgs += @("--resolution", $env:resolution)
}
if ($env:upgrade -eq "true") {
  $uvArgs += "--upgrade"
}
uv sync @uvArgs --project py-polars-expressions-testing --group dev
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

test

Run tests for py-polars-expressions-testing.

unit

Run py-polars-expressions-testing unit tests, matching .github/workflows/test-py-polars-unit.yml.

OPTIONS * resolution * flags: -r --resolution * type: string * desc: Dependency resolution strategy for uv (highest, lowest, lowest-direct) * upgrade * flags: -U --upgrade * desc: Allow package upgrades, ignoring pinned versions in uv.lock

set -euo pipefail
uv_args=()
if [ -n "${resolution:-}" ]; then
  uv_args+=(--resolution "$resolution")
fi
if [ "${upgrade:-}" = "true" ]; then
  uv_args+=(--upgrade)
fi
uv run "${uv_args[@]}" --project py-polars-expressions-testing --group test pytest -n auto py-polars-expressions-testing/tests/unit

$ErrorActionPreference = "Stop"
$uvArgs = @()
if ($env:resolution) {
  $uvArgs += @("--resolution", $env:resolution)
}
if ($env:upgrade -eq "true") {
  $uvArgs += "--upgrade"
}
uv run @uvArgs --project py-polars-expressions-testing --group test pytest -n auto py-polars-expressions-testing/tests/unit
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

docs

Commands relating to the documentation (mkdocs.yml).

build

Build the static HTML documentation into site/ with strict validation enabled.

set -euo pipefail
uv run --with-requirements docs/source/requirements.txt mkdocs build --strict

$ErrorActionPreference = "Stop"
uv run --with-requirements docs/source/requirements.txt mkdocs build --strict
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

serve

Start a local live-reloading MkDocs development server (default: http://127.0.0.1:8000).

OPTIONS * addr * flags: -a --addr * type: string * desc: IP address and port to serve documentation on (default: 127.0.0.1:8000)

set -euo pipefail
uv run --with-requirements docs/source/requirements.txt mkdocs serve --dev-addr "${addr:-127.0.0.1:8000}"

$ErrorActionPreference = "Stop"
$devAddr = if ($env:addr) { $env:addr } else { "127.0.0.1:8000" }
uv run --with-requirements docs/source/requirements.txt mkdocs serve --dev-addr $devAddr
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

lint

Run ruff lint and formatting checks against the repository and docs/source/.

set -euo pipefail
uv run --project py-polars-bigquery --group dev ruff check --no-fix docs/source/
uv run --project py-polars-bigquery --group dev ruff format --diff docs/source/

$ErrorActionPreference = "Stop"
uv run --project py-polars-bigquery --group dev ruff check --no-fix docs/source/
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
uv run --project py-polars-bigquery --group dev ruff format --diff docs/source/
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

test

Run project test suites across Rust and Python workspaces.

unit

Run all unit tests (rust-arrow-bigquery, py-arrow-bigquery, py-polars-expressions-testing, and py-polars-bigquery).

OPTIONS * resolution * flags: -r --resolution * type: string * desc: Dependency resolution strategy for uv (highest, lowest, lowest-direct) * upgrade * flags: -U --upgrade * desc: Allow package upgrades, ignoring pinned versions in uv.lock

set -euo pipefail
mask_args=()
if [ -n "${resolution:-}" ]; then
  mask_args+=(--resolution "$resolution")
fi
if [ "${upgrade:-}" = "true" ]; then
  mask_args+=(--upgrade)
fi
$MASK rust-arrow-bigquery test unit
$MASK py-arrow-bigquery test unit "${mask_args[@]}"
$MASK py-polars-expressions-testing test unit "${mask_args[@]}"
$MASK py-polars-bigquery test unit "${mask_args[@]}"

$ErrorActionPreference = "Stop"
$maskArgs = @()
if ($env:resolution) {
  $maskArgs += @("--resolution", $env:resolution)
}
if ($env:upgrade -eq "true") {
  $maskArgs += "--upgrade"
}
& $env:MASK rust-arrow-bigquery test unit
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& $env:MASK py-arrow-bigquery test unit @maskArgs
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& $env:MASK py-polars-expressions-testing test unit @maskArgs
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& $env:MASK py-polars-bigquery test unit @maskArgs
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

integration

Run all BigQuery integration tests (rust-arrow-bigquery, py-arrow-bigquery, and py-polars-bigquery). Requires GOOGLE_CLOUD_PROJECT.

set -euo pipefail
$MASK rust-arrow-bigquery test integration
$MASK py-arrow-bigquery test integration
$MASK py-polars-bigquery test integration

$ErrorActionPreference = "Stop"
& $env:MASK rust-arrow-bigquery test integration
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& $env:MASK py-arrow-bigquery test integration
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& $env:MASK py-polars-bigquery test integration
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

benchmark

Run all BigQuery benchmark tests locally (rust-arrow-bigquery and py-polars-bigquery). Requires GOOGLE_CLOUD_PROJECT.

set -euo pipefail
$MASK rust-arrow-bigquery test benchmark
$MASK py-polars-bigquery test benchmark

$ErrorActionPreference = "Stop"
& $env:MASK rust-arrow-bigquery test benchmark
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& $env:MASK py-polars-bigquery test benchmark
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }