Installation#

Built distributions#

The easiest way to install Spherely is via its binary packages available for Linux, MacOS, and Windows platforms on conda-forge and PyPI.

Installation of Python binary wheels (PyPI)#

Install the last released binary wheel, e.g., using pip:

$ pip install spherely

Installation of Conda packages (conda-forge)#

Install the last released conda-forge package using conda:

$ conda install spherely --channel conda-forge

Installation from source#

Compiling and installing Spherely from source may be useful for development purpose and/or for building it against a specific version of S2Geography and/or S2Geometry.

Requirements#

Additional build dependencies:

Cloning the source repository#

Spherely’s source code can be downloaded by cloning its source repository:

$ git clone https://github.com/benbovy/spherely
$ cd spherely

Setting up a development environment using pixi#

Spherely provides everything needed to manage its dependencies and run common tasks via pixi.

If you have pixi installed, you can install a complete development environment for your platform simply by executing the following command from Spherely’s project root directory:

$ pixi install --environment all

Running the command below from Spherely’s root directory will install all required tools and dependencies (if not installed yet) in a local environment, build and install Spherely (if needed) and run the tests:

$ pixi run tests

All available tasks are detailed in the pyproject.toml file or listed via the following command:

$ pixi task list

Setting up a development environment using conda#

If you don’t have pixi installed, you can follow the steps below to manually setup a conda environment for developing Spherely.

After cloning Spherely’s source repository, create a conda environment with the required (and development) dependencies using the ci/environment-dev.yml file:

$ conda env create -f ci/environment-dev.yml
$ conda activate spherely-dev

Build and install Spherely:

$ python -m pip install . -v --no-build-isolation

Note that you can specify a build directory in order to avoid rebuilding the whole library from scratch each time after editing the code:

$ python -m pip install . -v --no-build-isolation --config-settings build-dir=build/skbuild

Run the tests:

$ pytest . -v

Spherely also uses pre-commit for code auto-formatting and linting at every commit. After installing it, you can enable pre-commit hooks with the following command:

$ pre-commit install

(Note: you can skip the pre-commit checks with git commit --no-verify)

Using the latest S2Geography version#

If you want to compile Spherely against the latest version of S2Geography, use:

$ git clone https://github.com/paleolimbot/s2geography
$ cmake \
$     -S s2geography \
$     -B s2geography/build \
$     -DCMAKE_CXX_STANDARD=17 \
$     -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX
$ cmake --build s2geography/build
$ cmake --install s2geography/build