Skip to content

Development

Repository Layout

polypix/
  __init__.py        Python API and input validation
  __init__.pyi       public typing stub
  py.typed           PEP 561 marker
src/polypix/
  core.cpp           spherical geometry and HEALPix implementation
  core.h             native API declarations
  module.cpp         nanobind bindings
tests/
  test_polypix.py    behavior tests
docs/
  *.md               Zensical documentation pages

Build Model

Polypix uses scikit-build-core and CMake for Python extension builds. The normal dependency path is:

  • nanobind from the build environment,
  • healpix_cxx from the build environment,
  • C++17 compiler from the build environment.

Native dependencies are expected to come from the active build environment. In development, Pixi provides them from conda-forge.

Common Commands

Run tests:

pixi run test

Configure a manual CMake build:

pixi run configure

Compile the extension in that manual build tree:

pixi run compile

Build documentation:

pixi run docs-build

Preview documentation:

pixi run docs-serve

Build a wheel in the active Pixi environment:

pixi run wheel

This is a local development wheel for smoke testing. It bundles runtime libraries from the active Pixi environment and is not the artifact to upload to PyPI.

Release Builds

Publishable wheels are built by .github/workflows/release.yml with cibuildwheel. The workflow prepares a pinned native dependency prefix, builds wheels, repairs them with auditwheel on Linux or delocate on macOS, and runs the test suite against the repaired wheels.

Publishing is release-driven: creating or publishing a GitHub release builds the source distribution and release wheels, then uploads them to PyPI through trusted publishing. Pull requests run a smaller wheel smoke matrix so packaging changes are checked before a release.

The published wheel targets are Linux x86_64 and macOS 11 or newer on Intel and Apple Silicon. The Linux wheels use a manylinux_2_34 image because the native runtime dependencies come from conda-forge. The macOS deployment target is 11.0 because the bundled conda-forge runtime libraries require macOS 11 or newer.

Stable ABI Build

The CMake build has an optional stable-ABI mode:

python -m build --wheel --no-isolation \
  --config-setting=cmake.define.POLYPIX_STABLE_ABI=ON

This mode requires Python 3.12 or newer. It is not part of the current release matrix, which builds version-specific CPython wheels.

Documentation Publishing

The documentation source lives in docs/ and is configured by zensical.toml. Build it locally with:

pixi run docs-build

The .github/workflows/docs.yml workflow builds the same site on pull requests and publishes site/ to GitHub Pages on pushes to main.

License And Notices

Polypix is distributed under GPL-3.0-or-later because binary wheels link against HEALPix C++, which is GPL-2.0-or-later. Keep these files current when native dependencies change:

  • LICENSE
  • THIRD_PARTY_NOTICES.md
  • ci/licenses/*

Release maintainers must ensure that source availability for GPL-covered bundled components matches the published binary wheel set.

Design Constraints

Polypix should keep the Python layer thin:

  • validate and normalize array inputs in Python,
  • do expensive geometry and HEALPix work in C++,
  • return NumPy arrays rather than Python lists for large results.

When adding public functions, update:

  • polypix/__init__.py,
  • polypix/__init__.pyi,
  • docs/api.md,
  • tests.