Installation

From source (pip)

git clone https://github.com/ryanpavlick/hyplan
cd hyplan
pip install -e .

From source (conda/mamba)

mamba env create --name hyplan --file environment.yml
mamba activate hyplan
pip install -e .

Optional extras

HyPlan keeps its core install lightweight and gates niche features behind optional dependency groups. Install one or more with the usual pip install hyplan[<extra>] syntax (combine multiple in a single bracket list, e.g. pip install -e .[clouds,mag]).

Extra

Pulls in

Enables

mag

geomag

Magnetic-declination correction in hyplan.exports.to_pilot_excel when include_mag_heading=True, and hyplan.geometry.true_to_magnetic().

clouds

earthengine-api, seaborn

The hyplan.clouds module — climatology and time-series cloud queries against Google Earth Engine. Requires a separately-authenticated GEE account.

dev

pytest, pytest-cov, ruff, mypy

The full test, lint, and type-check toolchain used in CI. Run pytest --cov=hyplan after installing.

None of the extras are required to run the core flight-planning, swath, or export workflows. If you only want to read the API reference or run the tutorial, the base install is enough.

Versioning

HyPlan uses setuptools-scm to derive its version automatically from git tags. There is no hardcoded version string to maintain.

  • Tagged commits produce clean versions: git tag v0.2.0 gives version 0.2.0.

  • Development installs between tags produce versions like 0.2.1.dev3+g1a2b3c4.

  • Check the current version with python -c "import hyplan; print(hyplan.__version__)".

To create a new release:

git tag v0.2.0
git push origin v0.2.0
pip install -e .  # rebuilds _version.py with the new tag

Library logging

HyPlan uses Python’s standard logging module under the hyplan namespace. Library code attaches no handlers itself, so log messages are silent by default. Call hyplan.setup_logging() once from a notebook, script, or CLI to attach a stream handler:

setup_logging(level=20, format='%(asctime)s %(name)s %(levelname)s: %(message)s')[source]

Attach a StreamHandler to the hyplan logger.

Library code uses logging.getLogger(__name__) everywhere and never configures handlers itself. Call this once from a notebook, script, or CLI to see hyplan’s INFO/WARNING messages. Idempotent — re-calling replaces the handler instead of stacking duplicates.

Return type:

None

Parameters:

Building the documentation

pip install sphinx myst-parser furo sphinx-autodoc-typehints
cd docs
make html

The built documentation will be in docs/_build/html/.