diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
index f6c950c..9cc00a2 100644
--- a/.github/workflows/build_docs.yml
+++ b/.github/workflows/build_docs.yml
@@ -6,29 +6,29 @@ on:
pull_request:
branches: ['*']
+permissions:
+ contents: write
+
jobs:
build-docs:
runs-on: ubuntu-22.04
steps:
- - uses: actions/checkout@v4.2.2
+ - uses: actions/checkout@v6.0.2
with:
submodules: recursive
- - uses: actions/setup-python@v5.3.0
+ - uses: astral-sh/setup-uv@v7
with:
- python-version: 3.11
+ python-version: '3.11'
- - name: Install dependencies
- run: |
- pip install --upgrade pip setuptools wheel
- pip install .[all]
+ - uses: extractions/setup-just@v2
- name: Build the book
- run: jupyter-book build docs/ --warningiserror --keep-going --all
+ run: just docs
- name: Upload artifacts
- uses: actions/upload-artifact@v4.4.3
+ uses: actions/upload-artifact@v6.0.0
with:
name: html
path: docs/_build/html
diff --git a/.github/workflows/lint_and_coverage.yml b/.github/workflows/lint_and_coverage.yml
index 723677c..8ec1ef1 100644
--- a/.github/workflows/lint_and_coverage.yml
+++ b/.github/workflows/lint_and_coverage.yml
@@ -6,32 +6,33 @@ on:
pull_request:
branches: ['*']
+permissions:
+ contents: read
+
jobs:
linting:
name: Lint and Coverage
runs-on: ubuntu-24.04
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v6.0.2
with:
submodules: recursive
- - uses: actions/setup-python@v5
+ - uses: astral-sh/setup-uv@v7
with:
- python-version: 3.11
+ python-version: '3.11'
- - name: Install from source
- run: pip install .[test]
+ - uses: extractions/setup-just@v2
- - name: Run Linting
- uses: astral-sh/ruff-action@v3
+ - name: Lint
+ run: just lint
- - name: Coverage Requirement - Library
- run: |
- pytest tests/test_lib --cov=h3 --cov=tests/test_lib --cov-fail-under=100
+ - name: Install
+ run: uv sync
+
+ - name: Coverage - Library
+ run: just ci-test
- name: Coverage - Cython
- run: |
- pip install cython
- cythonize tests/test_cython/cython_example.pyx
- pytest tests/test_cython --cov=tests/test_cython
+ run: just ci-test-cython
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index cd4153d..f7a9854 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -14,17 +14,19 @@ jobs:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-22.04]
- python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']
+ python-version: ['3.10', '3.11', '3.12', '3.13', '3.14', '3.14t', '3.15', '3.15t']
steps:
- - uses: actions/checkout@v4.2.2
+ - uses: actions/checkout@v6.0.2
with:
submodules: recursive
- - uses: actions/setup-python@v5.3.0
+ - uses: astral-sh/setup-uv@v7
with:
python-version: '${{ matrix.python-version }}'
+ - uses: extractions/setup-just@v2
+
## Start Windows stuff
- uses: ilammy/msvc-dev-cmd@v1.13.0
if: startsWith(matrix.os, 'windows')
@@ -36,13 +38,11 @@ jobs:
echo "CXX=cl.exe" >> $GITHUB_ENV
## End Windows stuff
- - name: Install from source
- run: |
- pip install --upgrade pip setuptools wheel
- pip install .[test]
+ - name: Install
+ run: uv sync
- name: Tests
- run: |
- pip install cython
- cythonize tests/test_cython/cython_example.pyx
- pytest
+ run: just ci-test
+
+ - name: Cython Tests
+ run: just ci-test-cython
diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
index c70b891..1de5a80 100644
--- a/.github/workflows/wheels.yml
+++ b/.github/workflows/wheels.yml
@@ -23,32 +23,32 @@ jobs:
runs-on: ubuntu-22.04
steps:
- - uses: actions/checkout@v4.2.2
+ - uses: actions/checkout@v6.0.2
with:
submodules: recursive
- - name: Setup Python
- uses: actions/setup-python@v5.3.0
+ - uses: astral-sh/setup-uv@v7
with:
- python-version: 3.11
+ python-version: '3.11'
+
- name: Make sdist
- run: |
- python --version
- pipx --version
- pipx run build --sdist
+ run: uv build --sdist
+ # Test the sdist, NOT the local checkout.
+ # Use a fresh venv + uv pip install (not uv sync, which would build from source).
- name: Install from sdist
run: |
- pip install --upgrade pip setuptools wheel
+ uv venv
cp dist/h3-*.tar.gz h3.tar.gz
- pip install h3.tar.gz[test]
+ uv pip install h3.tar.gz[numpy] pytest pytest-cov
- name: Test sdist
- run: pytest
+ # run pytest directly from the venv to avoid `uv run` syncing from the local checkout
+ run: .venv/bin/pytest
- name: Upload artifacts to GitHub
- uses: actions/upload-artifact@v4.4.3
+ uses: actions/upload-artifact@v6.0.0
with:
name: temp_result_sdist
path: ./dist
@@ -60,27 +60,40 @@ jobs:
strategy:
matrix:
include:
- - os: macos-13
- build: 'cp*-macosx_x86_64'
- name: macOS13
- - os: macos-14
+ - os: macos-15
build: 'cp*-macosx_arm64'
- name: macOS14
+ name: macOS15
- os: windows-latest
build: 'cp3*-win_amd64'
name: Windows 64-bit
+ - os: windows-11-arm
+ build: 'cp311-win_arm64'
+ name: Windows ARM64 3.11
+ - os: windows-11-arm
+ build: 'cp312-win_arm64'
+ name: Windows ARM64 3.12
+ - os: windows-11-arm
+ build: 'cp313-win_arm64'
+ name: Windows ARM64 3.13
+ - os: windows-11-arm
+ build: 'cp314-win_arm64'
+ name: Windows ARM64 3.14
+ - os: windows-11-arm
+ build: 'cp314t-win_arm64'
+ name: Windows ARM64 3.14t
+ - os: windows-11-arm
+ build: 'cp315-win_arm64'
+ name: Windows ARM64 3.15
+ - os: windows-11-arm
+ build: 'cp315t-win_arm64'
+ name: Windows ARM64 3.15t
+
- os: ubuntu-22.04
build: 'cp*-manylinux_x86_64'
name: Linux Intel glibc 64-bit
- - os: ubuntu-22.04
- build: 'cp38-musllinux_x86_64'
- name: Linux Intel musl 64-bit 3.8
- - os: ubuntu-22.04
- build: 'cp39-musllinux_x86_64'
- name: Linux Intel musl 64-bit 3.9
- os: ubuntu-22.04
build: 'cp310-musllinux_x86_64'
name: Linux Intel musl 64-bit 3.10
@@ -93,13 +106,19 @@ jobs:
- os: ubuntu-22.04
build: 'cp313-musllinux_x86_64'
name: Linux Intel musl 64-bit 3.13
+ - os: ubuntu-22.04
+ build: 'cp314-musllinux_x86_64'
+ name: Linux Intel musl 64-bit 3.14
+ - os: ubuntu-22.04
+ build: 'cp314t-musllinux_x86_64'
+ name: Linux Intel musl 64-bit 3.14t
+ - os: ubuntu-22.04
+ build: 'cp315-musllinux_x86_64'
+ name: Linux Intel musl 64-bit 3.15
+ - os: ubuntu-22.04
+ build: 'cp315t-musllinux_x86_64'
+ name: Linux Intel musl 64-bit 3.15t
- - os: ubuntu-22.04
- build: 'cp38-manylinux_aarch64'
- name: Linux Aarch64 3.8
- - os: ubuntu-22.04
- build: 'cp39-manylinux_aarch64'
- name: Linux Aarch64 3.9
- os: ubuntu-22.04
build: 'cp310-manylinux_aarch64'
name: Linux Aarch64 3.10
@@ -112,14 +131,37 @@ jobs:
- os: ubuntu-22.04
build: 'cp313-manylinux_aarch64'
name: Linux Aarch64 3.13
+ - os: ubuntu-22.04
+ build: 'cp314-manylinux_aarch64'
+ name: Linux Aarch64 3.14
+ - os: ubuntu-22.04
+ build: 'cp314t-manylinux_aarch64'
+ name: Linux Aarch64 3.14t
+ - os: ubuntu-22.04
+ build: 'cp315-manylinux_aarch64'
+ name: Linux Aarch64 3.15
+ - os: ubuntu-22.04
+ build: 'cp315t-manylinux_aarch64'
+ name: Linux Aarch64 3.15t
steps:
- - uses: actions/checkout@v4.2.2
+ - uses: actions/checkout@v6.0.2
with:
submodules: recursive
- - uses: ilammy/msvc-dev-cmd@v1.13.0
- if: runner.os == 'Windows'
+ - uses: astral-sh/setup-uv@v7
+
+ - name: Set MSVC for Windows-x64
+ uses: microsoft/setup-msbuild@v2
+ if: matrix.os == 'windows-latest'
+ with:
+ msbuild-architecture: x64
+
+ - name: Set MSVC for Windows-ARM64
+ uses: microsoft/setup-msbuild@v2
+ if: matrix.os == 'windows-11-arm'
+ with:
+ msbuild-architecture: arm64
- name: Set Windows variables
if: runner.os == 'Windows'
@@ -130,23 +172,23 @@ jobs:
- name: Set up QEMU
if: runner.os == 'Linux'
- uses: docker/setup-qemu-action@v3.2.0
+ uses: docker/setup-qemu-action@v3.7.0
with:
platforms: aarch64
- - uses: pypa/cibuildwheel@v2.21.3
+ - uses: pypa/cibuildwheel@v4.2.1
env:
+ CIBW_BUILD_FRONTEND: 'build[uv]'
CIBW_TEST_REQUIRES: pytest pytest-cov numpy
CIBW_TEST_COMMAND: pytest {project}/tests
CIBW_ARCHS_LINUX: auto aarch64
CIBW_BUILD: ${{ matrix.build }}
- name: Check with Twine
- run: |
- pipx run twine check wheelhouse/*
+ run: uvx twine check wheelhouse/*
- name: Upload artifacts to GitHub
- uses: actions/upload-artifact@v4.4.3
+ uses: actions/upload-artifact@v6.0.0
with:
name: temp_result_${{ matrix.os }}-${{ strategy.job-index }}
path: wheelhouse/*.whl
@@ -156,7 +198,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Merge Artifacts
- uses: actions/upload-artifact/merge@v4.4.3
+ uses: actions/upload-artifact/merge@v6
with:
name: wheels_and_sdist
pattern: temp_result_*
@@ -164,17 +206,35 @@ jobs:
retention-days: 7
compression-level: 9
- to_pypi:
+ check_merged:
needs: [merge]
- if: github.event_name == 'release' && github.event.action == 'published'
runs-on: ubuntu-latest
-
steps:
- - uses: actions/download-artifact@v4.1.8
+ - uses: astral-sh/setup-uv@v7
+ with:
+ enable-cache: false
+ ignore-empty-workdir: true
+
+ - name: Download merged artifacts
+ uses: actions/download-artifact@v7.0.0
with:
name: wheels_and_sdist
path: dist
- - uses: pypa/gh-action-pypi-publish@v1.10.3
+ - name: Check all wheels and sdist with Twine
+ run: uvx twine check dist/*
+
+ to_pypi:
+ needs: [check_merged]
+ if: github.event_name == 'release' && github.event.action == 'published'
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/download-artifact@v7.0.0
+ with:
+ name: wheels_and_sdist
+ path: dist
+
+ - uses: pypa/gh-action-pypi-publish@v1.13.0
with:
password: ${{ secrets.pypi_password }}
diff --git a/.gitignore b/.gitignore
index ad8e4f3..1141de9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,74 +1,57 @@
-h3c/
+# Byte-compiled / optimized
*.py[cod]
-.cache/
-h3/out/
-.ruff_cache/
+__pycache__/
+
+# C extensions
+*.so
# Generated C code from Cython test
tests/**/*.c
# Cython HTML annotations
*.html
-# C extensions
-*.so
-
-# Packages
-*.egg
+# Build artifacts
+build/
+dist/
*.egg-info
-dist
-build
-eggs
-parts
-bin
-var
-sdist
-develop-eggs
-.installed.cfg
-# Installer logs
-pip-log.txt
-
-# Unit test / coverage reports
+# Coverage
.coverage
coverage.xml
coverage.lcov
-.tox
-nosetests.xml
-.noseids
-.pytest_cache
-
-# Mr Developer
-.mr.developer.cfg
-.project
-.pydevproject
-
-*.csv
-build/
-env/
-env_docs/
-docs/_build/
htmlcov/
-# vim/emacs backup files
+# Test
+.pytest_cache/
+
+# Tools
+.ruff_cache/
+.cache/
+
+# Docs
+_build/
+docs/_build/
+
+# Environment
+.venv/
+uv.lock
+
+# OS
+.DS_Store
+
+# Editor backup files
*~
\#*\#
.\#*
.*.sw*
-#DB snapshots
-db_snapshots/
-
-#OSX
-.DS_Store
-
-node_modules/
-bower_components/
-.sass-cache/
+# IDE
.idea/
-.unison.*
+# IPython / Jupyter
.ipynb_checkpoints/
-_skbuild/
-# might want to remove this later when distributing
-MANIFEST
+# Legacy build dirs
+_skbuild/
+h3c/
+h3/out/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6833583..0b6ee3a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,8 +15,83 @@ avoid adding features or APIs which do not map onto the
[H3 core API](https://uber.github.io/h3/#/documentation/api-reference/).
## Unreleased
+- Fix wheels for Python 3.14.6 free-threading
+- Add Python 3.14t, 3.15 and 3.15t wheels
+- Support `unit='rads'` in `average_hexagon_area` and `average_hexagon_edge_length` (#509)
+- Add `container` option to `h3shape_to_geo` (#495)
+- Fix Android cross-compilation with Buildozer (#494)
+- Raise `ValueError` instead of `assert` in `geo_to_h3shape` (#500, #502)
+- Fix `LatLngPoly` loop length check for closed rings (#505)
+- Return `False` from `is_valid_*` for out-of-range integers (#507)
+- Handle empty GeoJSON Polygon in `geo_to_h3shape` (#511)
+- Fix duplicate cells from `h3shape_to_cells_experimental` for `LatLngMultiPoly` (#512)
-- Update to v4.2.0. (#432)
+## [4.5.0] - 2026-05-29
+
+- Final v4.5 release includes all v4.5.x changes below
+
+## [4.5.0a3] - 2026-05-22
+
+- Update `h3lib` to v4.5.0 release (#491)
+
+## [4.5.0a2] - 2026-02-27
+
+- `cells_to_h3shape`/`cells_to_geo` now handle all valid cell sets, including
+ sets that would produce global polygons crossing the antimeridian, poles, or are larger than a hemisphere
+ - Duplicate cells now raise `H3DuplicateInputError`
+ - Mixed-resolution cells now raise `H3ResMismatchError`
+ - Internal: switch from linked-list to array-based C API for cells-to-polygon conversion
+
+## [4.5.0a1] - 2026-02-25
+
+- Update `h3lib` with draft v4.5 changes
+- Drop Python 3.8 and 3.9 (EOL); minimum is now Python 3.10
+- Document Python 3.14 support
+- Migrate build tooling from Makefile/pip to justfile/uv, including CI
+
+## [4.4.2] - 2026-01-29
+
+- Check for error from `cellsToLinkedMultiPolygon` (#477)
+
+## [4.4.1] - 2025-12-15
+
+- Fix PyPI publishing issue (#474)
+
+## [4.4.0] - 2025-12-12 (never published on PyPI)
+
+- Update `h3lib` to v4.4.1. (#470)
+ - Add new error codes:
+ - `H3IndexInvalidError`
+ - `H3BaseCellDomainError`
+ - `H3DigitDomainError`
+ - `H3DeletedDigitError`
+ - Add new functions:
+ - `is_valid_index`
+ - `get_index_digit`
+ - `construct_cell`
+ - `deconstruct_cell`
+
+## [4.3.1] - 2025-08-10
+
+- Build wheels for Windows on ARM64 (#463)
+
+## [4.3.0] - 2025-06-17
+
+- Update `h3lib` to v4.3.0. (#461)
+ - Uses `gridRing` (uber/h3#1016) instead of Cython fallback logic.
+
+## [4.2.2] - 2025-03-10
+
+- Update h3lib to v4.2.1. (#450)
+
+## [4.2.1] - 2025-01-31
+
+- Correct pyproject.toml links for PyPI (#441)
+- Update coverage badge (#443)
+
+## [4.2.0] - 2025-01-26
+
+- Update h3lib to v4.2.0. (#432)
- Add `h3shape_to_cells_experimental` (#436)
- Add `polygon_to_cells_experimental` alias
@@ -91,7 +166,7 @@ Beta release; feedback welcome!
- Website and API documentation; along with docstring cleanup.
- Add support for linters and IDE tooling (#213)
- Remove Py 3.5 wheel for Windows (#214)
-- Py 3.10 wheels and on more architectures (#220, #221, #223, #225)
+- Py 3.10 wheels and on more architectures (#220, #221, #223, #225)
- Greatly reduce sdist size (#227, #229)
## [3.7.3] - 2021-06-12
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 40ce38e..52a76f1 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,5 +1,16 @@
cmake_minimum_required(VERSION 3.15...3.26)
+# --- BEGIN ANDROID CROSS-COMPILATION FIX ---
+# Buildozer/python-for-android uses standard pip install which doesn't natively
+# pass a CMake toolchain file to scikit-build-core. This detects the Android compiler
+# from the environment and forces CMake into cross-compilation mode to prevent
+# it from building host (x86_64) binaries.
+if("$ENV{CC}" MATCHES "android" AND NOT DEFINED CMAKE_SYSTEM_NAME)
+ message(STATUS "Detected Android cross-compilation via environment variables. Setting CMAKE_SYSTEM_NAME=Android")
+ set(CMAKE_SYSTEM_NAME Android)
+endif()
+# --- END ANDROID CROSS-COMPILATION FIX ---
+
project(${SKBUILD_PROJECT_NAME} LANGUAGES C)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
diff --git a/dev_notes.md b/dev_notes.md
index 71d514d..65b4f62 100644
--- a/dev_notes.md
+++ b/dev_notes.md
@@ -2,11 +2,21 @@
## Install for development
-- `git clone git@github.com:uber/h3-py.git`
+This repo uses [`just`](https://github.com/casey/just) for running common development commands.
+
+To get started:
+
+- `git clone --recurse-submodules git@github.com:uber/h3-py.git`
+ - or fork the repository and `git clone --recurse-submodules https://github.com/{username}/h3-py.git`
- `cd h3-py`
-- `make init`
-- `make test`
-- `make lint`
+- `just lint`
+- `just test`
+- `just test-cython`
+
+To build and view docs:
+
+- `just docs`
+- `just view`
## Docstrings
@@ -49,6 +59,7 @@ git submodule update --init
- update `CHANGELOG.md` to reflect any changes since the last release
- update the `h3-py` version in `pyproject.toml`
+- if updating the C `h3lib` version, update the version badge on the readme
- create PR, get reviews, and merge with these changes
- go to https://github.com/uber/h3-py/releases and "Draft a new release"
- set the tag version and the release to the version. e.g., `v3.7.2`
diff --git a/docs/api_quick.md b/docs/api_quick.md
index 7b29638..6694ed4 100644
--- a/docs/api_quick.md
+++ b/docs/api_quick.md
@@ -25,6 +25,7 @@ and should be generally aligned with the
is_res_class_III
is_valid_directed_edge
is_valid_vertex
+ is_valid_index
```
## Index representation
@@ -49,6 +50,9 @@ and should be generally aligned with the
get_num_cells
get_resolution
get_base_cell_number
+ get_index_digit
+ construct_cell
+ deconstruct_cell
```
## Geographic coordinates
diff --git a/justfile b/justfile
new file mode 100644
index 0000000..d8e44fb
--- /dev/null
+++ b/justfile
@@ -0,0 +1,61 @@
+# disable editable installs so uv sync does a full build of the C extension
+export UV_NO_EDITABLE := "1"
+
+_:
+ just --list
+
+# force-rebuild the C extension to avoid stale builds
+reinstall:
+ uv cache clean h3
+ uv sync --reinstall-package h3
+
+# locally, always reinstall before testing
+test: reinstall ci-test
+test-cython: reinstall ci-test-cython
+
+fix:
+ uvx ruff check --fix
+
+lab:
+ uv sync --group docs
+ uv run jupyter lab
+
+view:
+ open docs/_build/html/index.html
+
+purge:
+ just _rm .venv
+ just _rm '*.pytest_cache'
+ just _rm .DS_Store
+ just _rm '*.egg-info'
+ just _rm dist
+ just _rm '*.ipynb_checkpoints'
+ just _rm __pycache__
+ just _rm uv.lock
+ just _rm .coverage
+ just _rm build
+ just _rm _build
+ just _rm _skbuild
+ just _rm .ruff_cache
+ uv cache clean h3
+
+_rm pattern:
+ -@find . -name "{{pattern}}" -prune -exec rm -rf {} +
+
+
+# Recipes below are used by CI workflows (.github/workflows/).
+# Changes here may break CI — update the workflows accordingly.
+
+ci-test:
+ uv run pytest tests/test_lib --cov=h3 --cov=tests/test_lib --cov-fail-under=100
+
+ci-test-cython:
+ uv run --with cython --with setuptools cythonize tests/test_cython/cython_example.pyx
+ uv run pytest tests/test_cython --cov=tests/test_cython
+
+lint:
+ uvx ruff check
+
+docs:
+ uv sync --group docs
+ uv run jupyter-book build docs/ --warningiserror --keep-going --all
diff --git a/makefile b/makefile
deleted file mode 100644
index df39c8f..0000000
--- a/makefile
+++ /dev/null
@@ -1,52 +0,0 @@
-.PHONY: init clear rebuild purge test lint lab ipython
-
-PYTHON=$(shell command -v python || command -v python3)
-
-
-build-docs:
- ./env/bin/pip install .[all]
- ./env/bin/jupyter-book build docs/ --warningiserror --keep-going --all
-
-open:
- open docs/_build/html/index.html
-
-init: purge
- git submodule update --init
- $(PYTHON) -m venv env
- ./env/bin/pip install --upgrade pip wheel setuptools
- ./env/bin/pip install .[test]
-
-clear:
- -./env/bin/pip uninstall -y h3
- -@rm -rf MANIFEST
- -@rm -rf .pytest_cache _skbuild dist .coverage build docs/_build .ruff_cache
- -@find . -type d -name '__pycache__' | xargs rm -r
- -@find . -type d -name '*.egg-info' | xargs rm -r
- -@find . -type f -name '*.pyc' | xargs rm -r
- -@find . -type f -name '*.so' | xargs rm -r
- -@find . -type d -name '*.ipynb_checkpoints' | xargs rm -r
- -@find ./tests -type f -name '*.c' | xargs rm -r
- -@find ./tests -type f -name '*.html' | xargs rm -r
-
-rebuild: clear
- ./env/bin/pip install .[test]
-
-purge: clear
- -@rm -rf env
-
-test:
- ./env/bin/pytest tests/test_lib --cov=h3 --cov=tests/test_lib --cov-fail-under=100
-
- ./env/bin/pip install cython
- ./env/bin/cythonize tests/test_cython/cython_example.pyx
- ./env/bin/pytest tests/test_cython --cov=tests/test_cython
-
-lint:
- ./env/bin/ruff check
-
-fix:
- ./env/bin/ruff check --fix
-
-lab:
- ./env/bin/pip install .[all]
- ./env/bin/jupyter lab
diff --git a/pyproject.toml b/pyproject.toml
index 06ce0e3..4430799 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build'
[project]
name = 'h3'
-version = '4.2.0'
+version = '4.5.0'
description = "Uber's hierarchical hexagonal geospatial indexing system"
readme = 'readme.md'
license = {file = 'LICENSE'}
@@ -14,7 +14,7 @@ authors = [
maintainers = [
{ name = 'AJ Friend', email = 'ajfriend@gmail.com' },
]
-requires-python = '>=3.8'
+requires-python = '>=3.10'
dependencies = []
@@ -25,12 +25,13 @@ classifiers = [
'License :: OSI Approved :: Apache Software License',
'Programming Language :: C',
'Programming Language :: Cython',
- 'Programming Language :: Python :: 3.8',
- 'Programming Language :: Python :: 3.9',
'Programming Language :: Python :: 3.10',
'Programming Language :: Python :: 3.11',
'Programming Language :: Python :: 3.12',
'Programming Language :: Python :: 3.13',
+ 'Programming Language :: Python :: 3.14',
+ 'Programming Language :: Python :: 3.15',
+ 'Programming Language :: Python :: Free Threading',
'Operating System :: MacOS :: MacOS X',
'Operating System :: POSIX :: Linux',
'Operating System :: Microsoft :: Windows',
@@ -38,19 +39,21 @@ classifiers = [
]
[project.urls]
-Homepage = 'https://github.com/organization/package'
-Documentation = 'https://package.readthedocs.io/'
-'Bug Tracker' = 'https://github.com/organization/package/issues'
-Discussions = 'https://github.com/organization/package/discussions'
-Changelog = 'https://package.readthedocs.io/en/latest/changelog.html'
+Homepage = 'https://github.com/uber/h3-py'
+Documentation = 'https://uber.github.io/h3-py/'
+'Bug Tracker' = 'https://github.com/uber/h3-py/issues'
+Discussions = 'https://github.com/uber/h3-py/discussions'
+Changelog = 'https://uber.github.io/h3-py/_changelog.html'
[project.optional-dependencies]
numpy = ['numpy']
-test = ['pytest', 'pytest-cov', 'ruff', 'numpy']
-all = [
- 'h3[test]',
- 'jupyter-book',
+
+[dependency-groups]
+dev = ['pytest', 'pytest-cov', 'numpy']
+docs = [
+ 'numpy',
+ 'jupyter-book<2',
'sphinx>=7.3.3', # https://github.com/sphinx-doc/sphinx/issues/12290
'jupyterlab',
'jupyterlab-geojson',
@@ -73,18 +76,25 @@ omit = [
]
+[tool.uv]
+default-groups = ['dev']
+
[tool.scikit-build]
sdist.exclude = [
'src/h3lib',
'docs',
'dev_notes.md',
- 'makefile',
+ 'justfile',
+ '.github',
+ '.gitignore',
+ '.gitmodules',
]
sdist.include = [
'src/h3lib/LICENSE',
'src/h3lib/README.md',
'src/h3lib/VERSION',
'src/h3lib/CMakeLists.txt',
+ 'src/h3lib/h3.pc.in',
'src/h3lib/cmake/*',
'src/h3lib/src/h3lib/*'
]
diff --git a/readme.md b/readme.md
index 4a8a4b5..8cb052b 100644
--- a/readme.md
+++ b/readme.md
@@ -1,15 +1,15 @@
-
+
# **h3-py**: Uber's H3 Hexagonal Hierarchical Geospatial Indexing System in Python
[](https://badge.fury.io/py/h3)
[](https://pypistats.org/packages/h3)
[](https://anaconda.org/conda-forge/h3-py)
-[](https://github.com/uber/h3/releases/tag/v4.1.0)
+[](https://github.com/uber/h3/releases/tag/v4.5.0)
[](https://github.com/uber/h3-py/blob/master/LICENSE)
[](https://github.com/uber/h3-py/actions)
-[](https://codecov.io/gh/uber/h3-py)
+[](https://github.com/uber/h3-py/blob/master/.github/workflows/lint_and_coverage.yml#L31)
Python bindings for the [H3 core library](https://h3geo.org/).
diff --git a/src/h3/__init__.py b/src/h3/__init__.py
index 4f7cb32..1e4f4b8 100644
--- a/src/h3/__init__.py
+++ b/src/h3/__init__.py
@@ -26,4 +26,8 @@ from ._cy import (
H3MemoryAllocError,
H3MemoryBoundsError,
H3OptionInvalidError,
+ H3IndexInvalidError,
+ H3BaseCellDomainError,
+ H3DigitDomainError,
+ H3DeletedDigitError,
)
diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py
index 627f3b9..70fa087 100644
--- a/src/h3/_cy/__init__.py
+++ b/src/h3/_cy/__init__.py
@@ -14,10 +14,13 @@ function interface and input conversion (string to int, for instance).
"""
from .cells import (
+ is_valid_index,
is_valid_cell,
is_pentagon,
get_base_cell_number,
get_resolution,
+ get_index_digit,
+ construct_cell,
cell_to_parent,
grid_distance,
grid_disk,
@@ -109,4 +112,11 @@ from .error_system import (
H3MemoryAllocError,
H3MemoryBoundsError,
H3OptionInvalidError,
+ H3IndexInvalidError,
+ H3BaseCellDomainError,
+ H3DigitDomainError,
+ H3DeletedDigitError,
+
+ get_H3_ERROR_END,
+ error_code_to_exception,
)
diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd
index 06b35ee..1bc31b8 100644
--- a/src/h3/_cy/cells.pxd
+++ b/src/h3/_cy/cells.pxd
@@ -1,9 +1,12 @@
from .h3lib cimport bool, int64_t, H3int
+cpdef bool is_valid_index(H3int h)
cpdef bool is_valid_cell(H3int h)
cpdef bool is_pentagon(H3int h)
cpdef int get_base_cell_number(H3int h) except -1
cpdef int get_resolution(H3int h) except -1
+cpdef int get_index_digit(H3int h, int res) except -1
+cpdef H3int construct_cell(int baseCellNumber, const int[:] digits) except 0
cpdef int grid_distance(H3int h1, H3int h2) except -1
cpdef H3int[:] grid_disk(H3int h, int k)
cpdef H3int[:] grid_ring(H3int h, int k)
diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx
index 2b57af2..f0667e5 100644
--- a/src/h3/_cy/cells.pyx
+++ b/src/h3/_cy/cells.pyx
@@ -1,13 +1,17 @@
+# cython: freethreading_compatible=True
cimport h3lib
from .h3lib cimport bool, int64_t, H3int, H3ErrorCodes
from .util cimport (
check_cell,
- check_res, # we don't use?
+ check_index,
check_distance,
)
+from .util import EARTH_RADIUS_KM
+
from .error_system cimport (
+ H3Error,
check_for_error,
check_for_error_msg,
)
@@ -19,6 +23,14 @@ from .memory cimport (
# todo: add notes about Cython exception handling
+cpdef bool is_valid_index(H3int h):
+ """Validates an H3 index (cell, vertex, or directed edge).
+
+ Returns
+ -------
+ boolean
+ """
+ return h3lib.isValidIndex(h) == 1
# bool is a python type, so we don't need the except clause
cpdef bool is_valid_cell(H3int h):
@@ -49,6 +61,33 @@ cpdef int get_resolution(H3int h) except -1:
return h3lib.getResolution(h)
+cpdef int get_index_digit(H3int h, int res) except -1:
+ cdef:
+ int digit
+
+ check_index(h)
+
+ check_for_error(
+ h3lib.getIndexDigit(h, res, &digit)
+ )
+
+ return digit
+
+cpdef H3int construct_cell(int base_cell_number, const int[:] digits) except 0:
+ cdef:
+ H3int out
+ int res = len(digits)
+ H3Error err
+
+ if res > 0:
+ err = h3lib.constructCell(res, base_cell_number, &digits[0], &out)
+ else:
+ err = h3lib.constructCell(res, base_cell_number, NULL, &out)
+
+ check_for_error(err)
+
+ return out
+
cpdef int grid_distance(H3int h1, H3int h2) except -1:
""" Compute the grid distance between two cells
@@ -87,41 +126,6 @@ cpdef H3int[:] grid_disk(H3int h, int k):
return mv
-cpdef H3int[:] _ring_fallback(H3int h, int k):
- """
- `ring` tries to call `h3lib.hexRing` first; if that fails, we call
- this function, which relies on `h3lib.kRingDistances`.
-
- Failures for `h3lib.hexRing` happen when the algorithm runs into a pentagon.
- """
- cdef:
- int64_t n
- int[:] distances ## todo: weird, this needs to be specified to avoid errors. cython bug?
-
- check_cell(h)
- check_distance(k)
-
- check_for_error(
- h3lib.maxGridDiskSize(k, &n)
- )
- hmm = H3MemoryManager(n)
-
- # parallel array of cell distances from `h`.
- # idea: instead of a memoryview object, have a my_mv object that can return a ptr, but does the correct logic when it has length 0
- # then can always just return the pointer, instead of the weird &mv[0] syntax
- distances = int_mv(n)
- check_for_error(
- h3lib.gridDiskDistances(h, k, hmm.ptr, &distances[0])
- )
-
- for i,v in enumerate(distances):
- if v != k:
- hmm.ptr[i] = 0
-
- mv = hmm.to_mv()
-
- return mv
-
cpdef H3int[:] grid_ring(H3int h, int k):
""" Return cells at grid distance `== k` from `h`.
Collection is "hollow" for k >= 1.
@@ -131,11 +135,10 @@ cpdef H3int[:] grid_ring(H3int h, int k):
n = 6*k if k > 0 else 1
hmm = H3MemoryManager(n)
- err = h3lib.gridRingUnsafe(h, k, hmm.ptr)
- if err:
- mv = _ring_fallback(h, k)
- else:
- mv = hmm.to_mv()
+ check_for_error(
+ h3lib.gridRing(h, k, hmm.ptr)
+ )
+ mv = hmm.to_mv()
return mv
@@ -321,7 +324,8 @@ cpdef double average_hexagon_area(int resolution, unit='km^2') except -1:
# todo: multiple units
convert = {
'km^2': 1.0,
- 'm^2': 1000*1000.0
+ 'm^2': 1000*1000.0,
+ 'rads^2': 1.0/(EARTH_RADIUS_KM*EARTH_RADIUS_KM),
}
try:
diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx
index bd0aa7c..7364bd5 100644
--- a/src/h3/_cy/edges.pyx
+++ b/src/h3/_cy/edges.pyx
@@ -1,8 +1,11 @@
+# cython: freethreading_compatible=True
cimport h3lib
from .h3lib cimport bool, H3int
from .error_system cimport check_for_error
+from .util import EARTH_RADIUS_KM
+
from .memory cimport H3MemoryManager
# todo: make bint
@@ -85,7 +88,8 @@ cpdef double average_hexagon_edge_length(int resolution, unit='km') except -1:
# todo: multiple units
convert = {
'km': 1.0,
- 'm': 1000.0
+ 'm': 1000.0,
+ 'rads': 1.0/EARTH_RADIUS_KM,
}
try:
diff --git a/src/h3/_cy/error_system.pxd b/src/h3/_cy/error_system.pxd
index af8c709..4a1e3b4 100644
--- a/src/h3/_cy/error_system.pxd
+++ b/src/h3/_cy/error_system.pxd
@@ -1,3 +1,6 @@
from .h3lib cimport H3Error
+
+cpdef error_code_to_exception(H3Error err)
cdef check_for_error(H3Error err)
cdef check_for_error_msg(H3Error err, str msg)
+cpdef H3Error get_H3_ERROR_END()
diff --git a/src/h3/_cy/error_system.pyx b/src/h3/_cy/error_system.pyx
index fbdd918..5fe5cd9 100644
--- a/src/h3/_cy/error_system.pyx
+++ b/src/h3/_cy/error_system.pyx
@@ -1,3 +1,4 @@
+# cython: freethreading_compatible=True
"""
Exceptions from the h3-py library have three possible sources:
@@ -60,6 +61,10 @@ Summarizing, all exceptions originating from the C library inherit from
- H3MemoryAllocError
- H3MemoryBoundsError
- H3OptionInvalidError
+- H3IndexInvalidError
+- H3BaseCellDomainError
+- H3DigitDomainError
+- H3DeletedDigitError
# TODO: add tests verifying that concrete exception classes have the right error codes associated with them
@@ -87,6 +92,11 @@ from .h3lib cimport (
E_MEMORY_ALLOC,
E_MEMORY_BOUNDS,
E_OPTION_INVALID,
+ E_INDEX_INVALID,
+ E_BASE_CELL_DOMAIN,
+ E_DIGIT_DOMAIN,
+ E_DELETED_DIGIT,
+ H3_ERROR_END # sentinel value
)
@contextmanager
@@ -169,6 +179,10 @@ with _the_error(H3ValueError) as e:
class H3NotNeighborsError(e): ...
class H3ResMismatchError(e): ...
class H3OptionInvalidError(e): ...
+ class H3IndexInvalidError(e): ...
+ class H3BaseCellDomainError(e): ...
+ class H3DigitDomainError(e): ...
+ class H3DeletedDigitError(e): ...
"""
@@ -192,6 +206,10 @@ error_mapping = {
E_MEMORY_ALLOC: H3MemoryAllocError,
E_MEMORY_BOUNDS: H3MemoryBoundsError,
E_OPTION_INVALID: H3OptionInvalidError,
+ E_INDEX_INVALID: H3IndexInvalidError,
+ E_BASE_CELL_DOMAIN: H3BaseCellDomainError,
+ E_DIGIT_DOMAIN: H3DigitDomainError,
+ E_DELETED_DIGIT: H3DeletedDigitError,
}
# Go back and modify the class definitions so that each concrete exception
@@ -207,25 +225,37 @@ for code, ex in error_mapping.items():
# TODO: Move the helpers to util?
# TODO: Unclear how/where to expose these functions. cdef/cpdef?
-cdef code_to_exception(H3Error err):
+cpdef error_code_to_exception(H3Error err):
+ """
+ Return Python exception corresponding to integer error code
+ given via the H3ErrorCodes enum in `h3api.h.in` in the C library.
+ """
if err == E_SUCCESS:
return None
elif err in error_mapping:
return error_mapping[err]
else:
- raise UnknownH3ErrorCode(err)
+ return UnknownH3ErrorCode(err)
cdef check_for_error(H3Error err):
- ex = code_to_exception(err)
+ ex = error_code_to_exception(err)
if ex:
raise ex
+cpdef H3Error get_H3_ERROR_END():
+ """
+ Return integer H3_ERROR_END from the H3ErrorCodes enum
+ in `h3api.h.in` in the C library, which is one greater than
+ the last valid error code.
+ """
+ return H3_ERROR_END
+
# todo: There's no easy way to do `*args` in `cdef` functions, but I'm also
# not sure this even needs to be a Cython `cdef` function at all, or that
# any of the other helper functions need to be in Cython.
# todo: Revisit after we've played with this a bit.
# todo: also: maybe the extra messages aren't that much more helpful...
cdef check_for_error_msg(H3Error err, str msg):
- ex = code_to_exception(err)
+ ex = error_code_to_exception(err)
if ex:
raise ex(msg)
diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd
index 4a483b2..6ee3b41 100644
--- a/src/h3/_cy/h3lib.pxd
+++ b/src/h3/_cy/h3lib.pxd
@@ -29,6 +29,11 @@ cdef extern from 'h3api.h':
E_MEMORY_ALLOC = 13
E_MEMORY_BOUNDS = 14
E_OPTION_INVALID = 15
+ E_INDEX_INVALID = 16
+ E_BASE_CELL_DOMAIN = 17
+ E_DIGIT_DOMAIN = 18
+ E_DELETED_DIGIT = 19
+ H3_ERROR_END # sentinel value
ctypedef struct LatLng:
double lat # in radians
@@ -42,21 +47,6 @@ cdef extern from 'h3api.h':
int i
int j
- ctypedef struct LinkedLatLng:
- LatLng data 'vertex'
- LinkedLatLng *next
-
- # renaming these for clarity
- ctypedef struct LinkedGeoLoop:
- LinkedLatLng *data 'first'
- LinkedLatLng *_data_last 'last' # not needed in Cython bindings
- LinkedGeoLoop *next
-
- ctypedef struct LinkedGeoPolygon:
- LinkedGeoLoop *data 'first'
- LinkedGeoLoop *_data_last 'last' # not needed in Cython bindings
- LinkedGeoPolygon *next
-
ctypedef struct GeoLoop:
int numVerts
LatLng *verts
@@ -71,12 +61,15 @@ cdef extern from 'h3api.h':
int isResClassIII(H3int h) nogil
int isValidDirectedEdge(H3int edge) nogil
int isValidVertex(H3int v) nogil
+ int isValidIndex(H3int h) nogil
double degsToRads(double degrees) nogil
double radsToDegs(double radians) nogil
int getResolution(H3int h) nogil
int getBaseCellNumber(H3int h) nogil
+ H3Error getIndexDigit(H3int h, int res, int *out) nogil
+ H3Error constructCell(int res, int baseCellNumber, const int *digits, H3int *out) nogil
H3Error latLngToCell(const LatLng *g, int res, H3int *out) nogil
H3Error cellToLatLng(H3int h, LatLng *) nogil
@@ -139,6 +132,7 @@ cdef extern from 'h3api.h':
H3Error localIjToCell(H3int origin, const CoordIJ *ij, uint32_t mode, H3int *out) nogil
H3Error gridDiskDistances(H3int origin, int k, H3int *out, int *distances) nogil
+ H3Error gridRing(H3int origin, int k, H3int *out) nogil
H3Error gridRingUnsafe(H3int origin, int k, H3int *out) nogil
H3Error areNeighborCells(H3int origin, H3int destination, int *out) nogil
@@ -162,18 +156,15 @@ cdef extern from 'h3api.h':
double greatCircleDistanceKm(const LatLng *a, const LatLng *b) nogil
double greatCircleDistanceM(const LatLng *a, const LatLng *b) nogil
- H3Error cellsToLinkedMultiPolygon(const H3int *h3Set, const int numCells, LinkedGeoPolygon *out)
- void destroyLinkedMultiPolygon(LinkedGeoPolygon *polygon)
-
H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count)
H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3int *out)
H3Error maxPolygonToCellsSizeExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count)
H3Error polygonToCellsExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t sz, H3int *out)
- # ctypedef struct GeoMultiPolygon:
- # int numPolygons
- # GeoPolygon *polygons
+ ctypedef struct GeoMultiPolygon:
+ int numPolygons
+ GeoPolygon *polygons
# int hexRange(H3int origin, int k, H3int *out)
@@ -190,3 +181,11 @@ cdef extern from 'h3api.h':
# void h3ToString(H3int h, char *str, size_t sz)
# void getH3intesFromUnidirectionalEdge(H3int edge, H3int *originDestination)
+
+
+# cellsToMultiPolygon and destroyGeoMultiPolygon are temporarily excluded
+# from the public API, so we use an internal header until they're moved
+# back into h3api.h
+cdef extern from 'cellsToMultiPoly.h':
+ H3Error cellsToMultiPolygon(const H3int *cells, const int64_t numCells, GeoMultiPolygon *out)
+ void destroyGeoMultiPolygon(GeoMultiPolygon *mpoly)
diff --git a/src/h3/_cy/latlng.pyx b/src/h3/_cy/latlng.pyx
index d83a9d3..630d3ad 100644
--- a/src/h3/_cy/latlng.pyx
+++ b/src/h3/_cy/latlng.pyx
@@ -1,3 +1,4 @@
+# cython: freethreading_compatible=True
from libc.stdint cimport uint64_t
cimport h3lib
@@ -261,11 +262,15 @@ def polygons_to_cells_experimental(polygons, int res, int flag):
# probably super inefficient, but it is working!
# tood: move this to C
+ # a cell can overlap more than one polygon, so skip the ones already added
+ seen = set()
k = 0
for mv in mvs:
for v in mv:
- hmm.ptr[k] = v
- k += 1
+ if v not in seen:
+ seen.add(v)
+ hmm.ptr[k] = v
+ k += 1
return hmm.to_mv()
diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx
index 0852105..963b00d 100644
--- a/src/h3/_cy/memory.pyx
+++ b/src/h3/_cy/memory.pyx
@@ -1,3 +1,4 @@
+# cython: freethreading_compatible=True
from cython.view cimport array
from .h3lib cimport H3int
diff --git a/src/h3/_cy/to_multipoly.pyx b/src/h3/_cy/to_multipoly.pyx
index db29baa..cb5e5e2 100644
--- a/src/h3/_cy/to_multipoly.pyx
+++ b/src/h3/_cy/to_multipoly.pyx
@@ -1,60 +1,46 @@
+# cython: freethreading_compatible=True
cimport h3lib
from h3lib cimport H3int
from .util cimport check_cell, coord2deg
+from .error_system cimport check_for_error
-# todo: it's driving me crazy that these three functions are all essentially the same linked list walker...
-# grumble: no way to do iterators in with cdef functions!
-cdef walk_polys(const h3lib.LinkedGeoPolygon* L):
- out = []
- while L:
- out += [walk_loops(L.data)]
- L = L.next
-
- return out
+cdef _loop_to_list(const h3lib.GeoLoop *loop):
+ return [coord2deg(loop.verts[v]) for v in range(loop.numVerts)]
-cdef walk_loops(const h3lib.LinkedGeoLoop* L):
- out = []
- while L:
- out += [walk_coords(L.data)]
- L = L.next
-
- return out
+cdef _poly_to_lists(const h3lib.GeoPolygon *poly):
+ return (
+ [_loop_to_list(&poly.geoloop)]
+ + [_loop_to_list(&poly.holes[h]) for h in range(poly.numHoles)]
+ )
-cdef walk_coords(const h3lib.LinkedLatLng* L):
- out = []
- while L:
- out += [coord2deg(L.data)]
- L = L.next
-
- return out
-
-# todo: tuples instead of lists?
def _to_multi_polygon(const H3int[:] cells):
cdef:
- h3lib.LinkedGeoPolygon polygon
+ h3lib.GeoMultiPolygon mpoly
+ H3int cell
- for h in cells:
- check_cell(h)
+ for cell in cells:
+ check_cell(cell)
- h3lib.cellsToLinkedMultiPolygon(&cells[0], len(cells), &polygon)
+ check_for_error(
+ h3lib.cellsToMultiPolygon(&cells[0], len(cells), &mpoly)
+ )
- out = walk_polys(&polygon)
-
- # we're still responsible for cleaning up the passed in `polygon`,
- # but not a problem here, since it is stack allocated
- h3lib.destroyLinkedMultiPolygon(&polygon)
+ try:
+ out = [
+ _poly_to_lists(&mpoly.polygons[p])
+ for p in range(mpoly.numPolygons)
+ ]
+ finally:
+ h3lib.destroyGeoMultiPolygon(&mpoly)
return out
def cells_to_multi_polygon(const H3int[:] cells):
- # todo: gotta be a more elegant way to handle these...
if len(cells) == 0:
return []
- multipoly = _to_multi_polygon(cells)
-
- return multipoly
+ return _to_multi_polygon(cells)
diff --git a/src/h3/_cy/util.pxd b/src/h3/_cy/util.pxd
index 4d7d962..b584d3a 100644
--- a/src/h3/_cy/util.pxd
+++ b/src/h3/_cy/util.pxd
@@ -8,6 +8,7 @@ cpdef H3str int_to_str(H3int x)
cdef check_cell(H3int h)
cdef check_edge(H3int e)
-cdef check_res(int res)
cdef check_vertex(H3int v)
+cdef check_index(H3int h)
+cdef check_res(int res)
cdef check_distance(int k)
diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx
index 7b8a9f2..74e8f80 100644
--- a/src/h3/_cy/util.pyx
+++ b/src/h3/_cy/util.pyx
@@ -1,4 +1,12 @@
-from .h3lib cimport H3int, H3str, isValidCell, isValidDirectedEdge, isValidVertex
+# cython: freethreading_compatible=True
+from .h3lib cimport (
+ H3int,
+ H3str,
+ isValidCell,
+ isValidDirectedEdge,
+ isValidVertex,
+ isValidIndex,
+)
cimport h3lib
@@ -7,9 +15,14 @@ from .error_system import (
H3DomainError,
H3DirEdgeInvalidError,
H3CellInvalidError,
- H3VertexInvalidError
+ H3VertexInvalidError,
+ H3IndexInvalidError,
)
+# Must match EARTH_RADIUS_KM in h3lib's constants.h, which is not part of the
+# public h3api.h header. Used to convert km based averages to radians.
+EARTH_RADIUS_KM = 6371.007180918475
+
cdef h3lib.LatLng deg2coord(double lat, double lng) nogil:
cdef:
h3lib.LatLng c
@@ -78,6 +91,10 @@ cdef check_vertex(H3int v):
if isValidVertex(v) == 0:
raise H3VertexInvalidError('Integer is not a valid H3 vertex: {}'.format(hex(v)))
+cdef check_index(H3int h):
+ if isValidIndex(h) == 0:
+ raise H3IndexInvalidError('Integer is not a valid H3 index: {}'.format(hex(h)))
+
cdef check_res(int res):
if (res < 0) or (res > 15):
raise H3ResDomainError(res)
diff --git a/src/h3/_cy/vertex.pyx b/src/h3/_cy/vertex.pyx
index 26a674a..99cc5ef 100644
--- a/src/h3/_cy/vertex.pyx
+++ b/src/h3/_cy/vertex.pyx
@@ -1,3 +1,4 @@
+# cython: freethreading_compatible=True
cimport h3lib
from h3lib cimport bool, H3int
diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py
index 5c36295..68d18c2 100644
--- a/src/h3/_h3shape.py
+++ b/src/h3/_h3shape.py
@@ -54,7 +54,7 @@ class LatLngPoly(H3Shape):
def __init__(self, outer, *holes):
loops = [outer] + list(holes)
for loop in loops:
- if len(loop) in (1, 2):
+ if len(loop) > 0 and len(_open_ring(loop)) < 3:
raise ValueError('Non-empty LatLngPoly loops need at least 3 points.')
point_dimensions = set(map(len, loop))
@@ -184,13 +184,6 @@ LL0: lat/lng or lng/lat pair
LL1: list of LL0s
LL2: list of LL1s (i.e., a polygon with holes)
LL3: list of LL2s (i.e., several polygons with holes)
-
-
-## TODO
-
-- Allow user to specify "container" in `cells_to_geojson`.
- - That is, they may want a MultiPolygon even if the output fits in a Polygon
- - 'auto', Polygon, MultiPolygon, FeatureCollection, GeometryCollection, ...
"""
@@ -230,6 +223,10 @@ def _remove_z(ll1):
def _LL2_to_polygon(ll2):
+ if len(ll2) == 0:
+ # empty GeoJSON Polygon, like `shapely.Polygon().__geo_interface__`
+ return LatLngPoly([])
+
ll2 = [
_remove_z(ll1)
for ll1 in ll2
@@ -308,7 +305,11 @@ def geo_to_h3shape(geo):
# get dict
geo = geo.__geo_interface__
- assert isinstance(geo, dict) # todo: remove
+ if not isinstance(geo, dict):
+ raise ValueError(
+ 'geo must be a dict or implement __geo_interface__, got: '
+ + str(type(geo))
+ )
t = geo['type']
coord = geo['coordinates']
@@ -325,14 +326,63 @@ def geo_to_h3shape(geo):
return shape
-def h3shape_to_geo(h3shape):
+def h3shape_to_geo(h3shape, container='auto'):
"""
Translate from an ``H3Shape`` to a ``__geo_interface__`` dict.
``h3shape`` should be either ``LatLngPoly`` or ``LatLngMultiPoly``
+ Parameters
+ ----------
+ container : str, optional
+ Specify the desired GeoJSON output container.
+ Options: 'auto', 'Polygon', 'MultiPolygon', 'Feature',
+ 'FeatureCollection', or 'GeometryCollection'.
+ Default is 'auto' (returns the simplest valid geometry).
+
Returns
-------
dict
"""
- return h3shape.__geo_interface__
+ base_geo = h3shape.__geo_interface__
+
+ # Return immediately if no wrapping is needed
+ if container == 'auto' or container == base_geo['type']:
+ return base_geo
+
+ # Upgrade a Polygon to a MultiPolygon if explicitly requested
+ if container == 'MultiPolygon' and base_geo['type'] == 'Polygon':
+ return {
+ 'type': 'MultiPolygon',
+ 'coordinates': (base_geo['coordinates'],)
+ }
+
+ if container == 'Feature':
+ return {
+ 'type': 'Feature',
+ 'geometry': base_geo,
+ 'properties': {}
+ }
+
+ if container == 'FeatureCollection':
+ return {
+ 'type': 'FeatureCollection',
+ 'features': [{
+ 'type': 'Feature',
+ 'geometry': base_geo,
+ 'properties': {}
+ }]
+ }
+
+ if container == 'GeometryCollection':
+ return {
+ 'type': 'GeometryCollection',
+ 'geometries': [base_geo]
+ }
+
+ # If we reach here, the requested container is either unknown or
+ # insufficient for the data (e.g., requesting a Polygon for MultiPolygon data).
+ raise ValueError(
+ f"Requested container '{container}' is invalid or insufficient "
+ f"for data of type '{base_geo['type']}'."
+ )
diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py
index 09f7deb..8eac4b1 100644
--- a/src/h3/api/basic_int/__init__.py
+++ b/src/h3/api/basic_int/__init__.py
@@ -1,5 +1,6 @@
# This file is **symlinked** across the APIs to ensure they are exactly the same.
from typing import Literal
+from array import array
from ... import _cy
from ..._h3shape import (
@@ -128,6 +129,20 @@ def average_hexagon_edge_length(res, unit='km'):
return _cy.average_hexagon_edge_length(res, unit)
+def is_valid_index(h):
+ """Validates *any* H3 index (cell, vertex, or directed edge).
+
+ Returns
+ -------
+ bool
+ """
+ try:
+ h = _in_scalar(h)
+ return _cy.is_valid_index(h)
+ except (ValueError, TypeError, OverflowError):
+ return False
+
+
def is_valid_cell(h):
"""
Validates an H3 cell (hexagon or pentagon).
@@ -139,13 +154,13 @@ def is_valid_cell(h):
try:
h = _in_scalar(h)
return _cy.is_valid_cell(h)
- except (ValueError, TypeError):
+ except (ValueError, TypeError, OverflowError):
return False
def is_valid_directed_edge(edge):
"""
- Validates an H3 unidirectional edge.
+ Validates an H3 directed edge.
Returns
-------
@@ -154,7 +169,7 @@ def is_valid_directed_edge(edge):
try:
e = _in_scalar(edge)
return _cy.is_valid_directed_edge(e)
- except (ValueError, TypeError):
+ except (ValueError, TypeError, OverflowError):
return False
@@ -459,8 +474,6 @@ def uncompact_cells(cells, res):
-----
There is currently no guaranteed order of the output cells.
"""
- # TODO: add test to make sure an error is returned when input contains cell
- # smaller than output res.
hc = _in_collection(cells)
hu = _cy.uncompact_cells(hc, res)
@@ -736,10 +749,124 @@ def get_base_cell_number(h):
Returns
-------
int
+
+ Examples
+ --------
+ >>> h = construct_cell(57, 2, 1, 4)
+ >>> h
+ '83728cfffffffff'
+ >> get_base_cell_number(h)
+ 57
"""
return _cy.get_base_cell_number(_in_scalar(h))
+def get_index_digit(h, res):
+ """
+ Get the index digit of a cell at the given resolution.
+
+ Parameters
+ ----------
+ h : H3Cell
+ Cell whose index digit will be returned.
+ res : int
+ Resolution (``>= 1``) at which to read the digit.
+
+ Returns
+ -------
+ int
+ The index digit at the requested resolution.
+
+ Examples
+ --------
+ >>> h = construct_cell(7, 2, 1, 4)
+ >>> h
+ '830e8cfffffffff'
+ >>> get_index_digit(h, 1)
+ 2
+ >>> get_index_digit(h, 2)
+ 1
+ >>> get_index_digit(h, 3)
+ 4
+ """
+ return _cy.get_index_digit(_in_scalar(h), res)
+
+
+def construct_cell(base_cell_number, *digits, res=None):
+ """
+ Construct cell from base cell and digits.
+
+ Parameters
+ ----------
+ base_cell_number : int
+ Base cell *number* (``0`` to ``121``).
+ *digits : int
+ Sequence of index digits (``0`` to ``6``).
+ Length of digits will be the resulting resolution of the output cell.
+ res : int, optional
+ Resolution of the constructed cell. If provided, it must equal
+ ``len(digits)``; otherwise it is inferred from the number of digits.
+
+ Returns
+ -------
+ H3Cell
+ The constructed cell.
+
+ Examples
+ --------
+ >>> construct_cell(7, 2, 1, 4) # resolution 3 cell
+ '830e8cfffffffff'
+
+ >>> construct_cell(15, 0, 0, 5, 3) # resolution 4 cell
+ '841e057ffffffff'
+
+ >>> construct_cell(15, 0, 0, 5, 3, res=4)
+ '841e057ffffffff'
+ """
+ if (res is not None) and (len(digits) != res):
+ raise ValueError('Resolution must match number of digits.')
+
+ digits = array('i', digits)
+ o = _cy.construct_cell(base_cell_number, digits)
+ return _out_scalar(o)
+
+
+def deconstruct_cell(h):
+ """
+ Deconstruct cell into base cell and digits.
+
+ Parameters
+ ----------
+ h : H3Cell
+ Cell to deconstruct.
+
+ Returns
+ -------
+ list of int
+ [base_cell_number, digit1, digit2, ..., digitN]
+
+ Examples
+ --------
+ >>> h = construct_cell(7, 2, 1, 4) # resolution 3 cell
+ >>> h
+ '830e8cfffffffff'
+ >>> deconstruct_cell(h)
+ (7, 2, 1, 4)
+
+ >>> h = construct_cell(15, 0, 0, 5, 3) # resolution 4 cell
+ >>> h
+ '841e057ffffffff'
+ >>> deconstruct_cell(h)
+ (15, 0, 0, 5, 3)
+ >>> construct_cell(*deconstruct_cell(h), 0) == cell_to_center_child(h)
+ """
+ res = get_resolution(h)
+ bc = get_base_cell_number(h)
+ digits = [get_index_digit(h, r + 1) for r in range(res)]
+
+ return [bc, *digits]
+
+
def are_neighbor_cells(h1, h2):
"""
Returns ``True`` if ``h1`` and ``h2`` are neighboring cells.
@@ -1236,5 +1363,30 @@ def is_valid_vertex(v):
try:
v = _in_scalar(v)
return _cy.is_valid_vertex(v)
- except (ValueError, TypeError):
+ except (ValueError, TypeError, OverflowError):
return False
+
+
+if _out_scalar is _in_scalar: # pragma: no cover
+ # When _out_scalar is identity (basic_int, numpy_int, memview_int),
+ # bind scalar functions directly to their _cy counterparts to eliminate
+ # Python call frame and identity wrapper overhead (Issue #501).
+ #
+ # Coverage is only measured on the basic_str copy of this file, where
+ # this branch is never taken; it is exercised by the int API tests.
+ for _name in (
+ 'latlng_to_cell',
+ 'cell_to_parent',
+ 'cell_to_center_child',
+ 'cells_to_directed_edge',
+ 'get_directed_edge_origin',
+ 'get_directed_edge_destination',
+ 'directed_edge_to_cells',
+ 'local_ij_to_cell',
+ 'cell_to_vertex',
+ ):
+ _fn = globals()[_name]
+ _cy_fn = getattr(_cy, _name)
+ _cy_fn.__doc__ = _fn.__doc__
+ globals()[_name] = _cy_fn
+ del _name, _fn, _cy_fn
diff --git a/src/h3lib b/src/h3lib
index 2d8a62d..1b536c3 160000
--- a/src/h3lib
+++ b/src/h3lib
@@ -1 +1 @@
-Subproject commit 2d8a62d5fe456bba2af7ca0be7efe9754f1dd25b
+Subproject commit 1b536c34225191ba24a75a840f634d4a48c3b206
diff --git a/tests/test_lib/polyfill/test_h3.py b/tests/test_lib/polyfill/test_h3.py
index 72ddd58..6327cf8 100644
--- a/tests/test_lib/polyfill/test_h3.py
+++ b/tests/test_lib/polyfill/test_h3.py
@@ -207,6 +207,20 @@ def test_poly_to_cells_experimental_mpoly():
))
+def test_poly_to_cells_experimental_mpoly_no_duplicates():
+ # cells that overlap both polygons should only be returned once
+ a = h3.LatLngPoly([(37.70, -122.50), (37.70, -122.45), (37.75, -122.45)])
+ b = h3.LatLngPoly([(37.70, -122.449), (37.70, -122.40), (37.75, -122.40)])
+ mpoly = h3.LatLngMultiPoly(a, b)
+
+ out = h3.h3shape_to_cells_experimental(mpoly, res=7, contain='overlap')
+
+ expected = set(h3.h3shape_to_cells_experimental(a, res=7, contain='overlap'))
+ expected |= set(h3.h3shape_to_cells_experimental(b, res=7, contain='overlap'))
+ assert len(out) == len(expected)
+ assert set(out) == expected
+
+
def test_polyfill_with_hole():
poly = h3.LatLngPoly(sf_7x7, sf_hole1)
@@ -302,6 +316,23 @@ def test_geo_to_h3shape_passthrough():
assert h3.geo_to_h3shape(shape) is shape
+def test_geo_to_h3shape_rejects_non_dict():
+ with pytest.raises(ValueError, match='dict or implement __geo_interface__'):
+ h3.geo_to_h3shape('not a geo object')
+
+
+def test_geo_to_h3shape_empty_polygon():
+ # e.g., shapely.Polygon().__geo_interface__
+ geo = MockGeoInterface({'type': 'Polygon', 'coordinates': ()})
+
+ shape = h3.geo_to_h3shape(geo)
+ assert isinstance(shape, h3.LatLngPoly)
+ assert shape.outer == ()
+ assert shape.holes == ()
+
+ assert h3.geo_to_cells(geo, 9) == []
+
+
def test_polyfill_down_under():
sydney = [
(-33.8556, 151.1979),
diff --git a/tests/test_lib/polyfill/test_polyfill.py b/tests/test_lib/polyfill/test_polyfill.py
index 9bdd9af..f70c639 100644
--- a/tests/test_lib/polyfill/test_polyfill.py
+++ b/tests/test_lib/polyfill/test_polyfill.py
@@ -151,6 +151,9 @@ def test_bad_geo_input():
with pytest.raises(ValueError):
h3.geo_to_cells({'type': 'not a shape', 'coordinates': None}, 9)
+ with pytest.raises(ValueError):
+ h3.geo_to_cells('not a shape', 9)
+
def test_cells_to_geo():
h = '89754e64993ffff'
diff --git a/tests/test_lib/polyfill/test_polygon_class.py b/tests/test_lib/polyfill/test_polygon_class.py
index 59e8da2..a3639b6 100644
--- a/tests/test_lib/polyfill/test_polygon_class.py
+++ b/tests/test_lib/polyfill/test_polygon_class.py
@@ -50,3 +50,16 @@ def test_bad_subclass():
with pytest.raises(ValueError):
h3.h3shape_to_cells_experimental(shoop, res=9)
+
+
+def test_closed_loop_with_too_few_points():
+ # a closed loop of 3 points only has 2 distinct points once the
+ # repeated closing point is removed
+ a, b = (37.68, -122.54), (37.82, -122.34)
+ outer = [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]
+
+ with pytest.raises(ValueError, match='at least 3 points'):
+ h3.LatLngPoly([a, b, a])
+
+ with pytest.raises(ValueError, match='at least 3 points'):
+ h3.LatLngPoly(outer, [a, b, a])
diff --git a/tests/test_lib/polyfill/test_to_multipoly.py b/tests/test_lib/polyfill/test_to_multipoly.py
index 61f77f6..80c5a75 100644
--- a/tests/test_lib/polyfill/test_to_multipoly.py
+++ b/tests/test_lib/polyfill/test_to_multipoly.py
@@ -1,9 +1,21 @@
-import h3
+import pytest
+import h3
+from h3._cy.error_system import H3DuplicateInputError, H3ResMismatchError, H3FailedError
from .. import util as u
+def assert_cells_roundtrip(cells):
+ """Convert cells to multi-polygon and back, checking we recover the original set."""
+ res = h3.get_resolution(cells[0])
+ mpoly = h3.cells_to_h3shape(cells, tight=False)
+
+ recovered = h3.h3shape_to_cells(mpoly, res)
+
+ assert u.same_set(recovered, cells)
+
+
def test_cells_to_h3shape():
h = '8928308280fffff'
cells = h3.grid_disk(h, 1)
@@ -47,3 +59,302 @@ def test_2_polys():
cells
)
assert set(map(len, out)) == {1, 12}
+
+
+def test_empty():
+ mpoly = h3.cells_to_h3shape([], tight=False)
+ assert isinstance(mpoly, h3.LatLngMultiPoly)
+ assert len(mpoly) == 0
+
+ mpoly = h3.cells_to_h3shape([], tight=True)
+ assert isinstance(mpoly, h3.LatLngMultiPoly)
+ assert len(mpoly) == 0
+
+
+def test_all_res0_cells():
+ cells = h3.get_res0_cells()
+ mpoly = h3.cells_to_h3shape(cells, tight=False)
+
+ # We should get an "entire globe" multipolygon back
+ # The current implementation returns 8 triangles
+ assert len(mpoly) == 8
+ for poly in mpoly:
+ assert len(poly.outer) == 3
+ assert len(poly.holes) == 0
+
+ # Roundtrip fails: h3shape_to_cells recovers only 69/122 cells.
+ # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons.
+ cells2 = h3.h3shape_to_cells(mpoly, 0)
+ assert len(cells2) == 69
+
+
+def test_pentagons():
+ for res in range(16):
+ cells = h3.get_pentagons(res)
+ mpoly = h3.cells_to_h3shape(cells, tight=False)
+
+ if res % 2 == 0:
+ expected_verts = 5
+ else:
+ # pentagons have distortion vertices at odd resolutions
+ expected_verts = 10
+
+ assert len(mpoly) == 12
+ for poly in mpoly:
+ assert len(poly.holes) == 0
+ assert len(poly.outer) == expected_verts
+
+ assert_cells_roundtrip(cells)
+
+
+def test_duplicate_cells_error():
+ cell = '8928308280fffff'
+ with pytest.raises(H3DuplicateInputError):
+ h3.cells_to_h3shape([cell, cell])
+
+
+def test_mixed_resolution_error():
+ with pytest.raises(H3ResMismatchError):
+ h3.cells_to_h3shape(['8027fffffffffff', '81efbffffffffff'])
+
+
+def test_three_polygons():
+ cells = [
+ '8027fffffffffff', '802bfffffffffff', '804dfffffffffff',
+ '8067fffffffffff', '806dfffffffffff', '8049fffffffffff',
+ '805ffffffffffff', '8057fffffffffff', '807dfffffffffff',
+ '80a5fffffffffff', '80a9fffffffffff', '808bfffffffffff',
+ '801bfffffffffff', '8035fffffffffff', '803ffffffffffff',
+ '8053fffffffffff', '8043fffffffffff', '8021fffffffffff',
+ '8011fffffffffff', '801ffffffffffff', '8097fffffffffff',
+ ]
+
+ mpoly = h3.cells_to_h3shape(cells, tight=False)
+
+ assert len(mpoly) == 3
+ hole_counts = [len(p.holes) for p in mpoly]
+
+ # Polygons are ordered by size, and we know the hole counts of each
+ assert hole_counts == [3, 1, 0]
+
+ assert_cells_roundtrip(cells)
+
+
+def test_issue_1049():
+ cells = [
+ '827487fffffffff', '82748ffffffffff', '827497fffffffff',
+ '82749ffffffffff', '8274affffffffff', '8274c7fffffffff',
+ '8274cffffffffff', '8274d7fffffffff', '8274e7fffffffff',
+ '8274effffffffff', '8274f7fffffffff', '82754ffffffffff',
+ '827c07fffffffff', '827c27fffffffff', '827c2ffffffffff',
+ '827c37fffffffff', '827d87fffffffff', '827d8ffffffffff',
+ '827d97fffffffff', '827d9ffffffffff', '827da7fffffffff',
+ '827daffffffffff', '82801ffffffffff', '8280a7fffffffff',
+ '8280affffffffff', '8280b7fffffffff', '828197fffffffff',
+ '82819ffffffffff', '8281a7fffffffff', '8281b7fffffffff',
+ '828207fffffffff', '82820ffffffffff', '828227fffffffff',
+ '82822ffffffffff', '8282e7fffffffff', '828307fffffffff',
+ '82830ffffffffff', '82831ffffffffff', '82832ffffffffff',
+ '828347fffffffff', '82834ffffffffff', '828357fffffffff',
+ '82835ffffffffff', '828367fffffffff', '828377fffffffff',
+ '82a447fffffffff', '82a457fffffffff', '82a45ffffffffff',
+ '82a467fffffffff', '82a46ffffffffff', '82a477fffffffff',
+ '82a4c7fffffffff', '82a4cffffffffff', '82a4d7fffffffff',
+ '82a4e7fffffffff', '82a4effffffffff', '82a4f7fffffffff',
+ '82a547fffffffff', '82a54ffffffffff', '82a557fffffffff',
+ '82a55ffffffffff', '82a567fffffffff', '82a577fffffffff',
+ '82a837fffffffff', '82a897fffffffff', '82a8a7fffffffff',
+ '82a8b7fffffffff', '82a917fffffffff', '82a927fffffffff',
+ '82a937fffffffff', '82a987fffffffff', '82a98ffffffffff',
+ '82a997fffffffff', '82a99ffffffffff', '82a9a7fffffffff',
+ '82a9affffffffff', '82ac47fffffffff', '82ac57fffffffff',
+ '82ac5ffffffffff', '82ac67fffffffff', '82ac6ffffffffff',
+ '82ac77fffffffff', '82ad47fffffffff', '82ad4ffffffffff',
+ '82ad57fffffffff', '82ad5ffffffffff', '82ad67fffffffff',
+ '82ad77fffffffff', '82c207fffffffff', '82c217fffffffff',
+ '82c227fffffffff', '82c237fffffffff', '82c287fffffffff',
+ '82c28ffffffffff', '82c29ffffffffff', '82c2a7fffffffff',
+ '82c2affffffffff', '82c2b7fffffffff', '82c307fffffffff',
+ '82c317fffffffff', '82c31ffffffffff', '82c337fffffffff',
+ '82cfb7fffffffff', '82d0c7fffffffff', '82d0d7fffffffff',
+ '82d0dffffffffff', '82d0e7fffffffff', '82d0f7fffffffff',
+ '82d147fffffffff', '82d157fffffffff', '82d15ffffffffff',
+ '82d167fffffffff', '82d177fffffffff', '82d187fffffffff',
+ '82d18ffffffffff', '82d197fffffffff', '82d19ffffffffff',
+ '82d1a7fffffffff', '82d1affffffffff', '82dc47fffffffff',
+ '82dc57fffffffff', '82dc5ffffffffff', '82dc67fffffffff',
+ '82dc6ffffffffff', '82dc77fffffffff', '82dcc7fffffffff',
+ '82dccffffffffff', '82dcd7fffffffff', '82dce7fffffffff',
+ '82dceffffffffff', '82dcf7fffffffff', '82dd1ffffffffff',
+ '82dd47fffffffff', '82dd4ffffffffff', '82dd57fffffffff',
+ '82dd5ffffffffff', '82dd6ffffffffff', '82dd87fffffffff',
+ '82dd8ffffffffff', '82dd97fffffffff', '82dd9ffffffffff',
+ '82ddaffffffffff', '82ddb7fffffffff', '82dec7fffffffff',
+ '82decffffffffff', '82ded7fffffffff', '82dee7fffffffff',
+ '82deeffffffffff', '82def7fffffffff', '82df0ffffffffff',
+ '82df1ffffffffff', '82df47fffffffff', '82df4ffffffffff',
+ '82df57fffffffff', '82df5ffffffffff', '82df77fffffffff',
+ '82df8ffffffffff', '82df9ffffffffff', '82e6c7fffffffff',
+ '82e6cffffffffff', '82e6d7fffffffff', '82e6dffffffffff',
+ '82e6effffffffff', '82e6f7fffffffff',
+ ]
+
+ mpoly = h3.cells_to_h3shape(cells, tight=False)
+
+ assert len(mpoly) == 12
+ for poly in mpoly:
+ assert len(poly.holes) == 0
+
+ assert_cells_roundtrip(cells)
+
+
+def test_equator_cells():
+ """Continuous band of cells overlapping the equator.
+ """
+ cells = [
+ '81807ffffffffff', '817efffffffffff', '81723ffffffffff',
+ '817ebffffffffff', '817c3ffffffffff', '817e3ffffffffff',
+ '817a3ffffffffff', '8166fffffffffff', '8172bffffffffff',
+ '816afffffffffff', '81933ffffffffff', '8168fffffffffff',
+ '8188fffffffffff', '81853ffffffffff', '817f7ffffffffff',
+ '8180bffffffffff', '81783ffffffffff', '81743ffffffffff',
+ '8170bffffffffff', '8173bffffffffff', '8179bffffffffff',
+ '817cbffffffffff', '8188bffffffffff', '81857ffffffffff',
+ '816f7ffffffffff', '8177bffffffffff', '81617ffffffffff',
+ '816f3ffffffffff', '8174bffffffffff', '8180fffffffffff',
+ '817a7ffffffffff', '81767ffffffffff', '81757ffffffffff',
+ '81957ffffffffff', '81787ffffffffff', '81847ffffffffff',
+ '81653ffffffffff', '817bbffffffffff', '816cfffffffffff',
+ '816abffffffffff', '815f3ffffffffff', '817c7ffffffffff',
+ '8168bffffffffff', '818cbffffffffff', '818cfffffffffff',
+ '818afffffffffff', '8174fffffffffff', '8172fffffffffff',
+ '8170fffffffffff', '816fbffffffffff', '81657ffffffffff',
+ '816c7ffffffffff', '8186bffffffffff', '81763ffffffffff',
+ '818a7ffffffffff', '8186fffffffffff', '81707ffffffffff',
+ '8182bffffffffff', '818f3ffffffffff', '8182fffffffffff',
+ ]
+ mpoly = h3.cells_to_h3shape(cells, tight=False)
+
+ assert len(mpoly) == 1
+ poly = mpoly[0]
+ assert len(poly.holes) == 1
+
+ # Roundtrip fails: h3shape_to_cells recovers only 18/60 cells.
+ # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons.
+ cells2 = h3.h3shape_to_cells(mpoly, 1)
+ assert len(cells2) == 18
+
+
+def test_prime_meridian():
+ """Continuous band of cells overlapping the prime meridian.
+ """
+ cells = [
+ '81efbffffffffff', '81c07ffffffffff', '81d1bffffffffff',
+ '81097ffffffffff', '8109bffffffffff', '81d0bffffffffff',
+ '81987ffffffffff', '81017ffffffffff', '81e67ffffffffff',
+ '81ddbffffffffff', '81ac7ffffffffff', '8158bffffffffff',
+ '81397ffffffffff', '81593ffffffffff', '81c17ffffffffff',
+ '81827ffffffffff', '81197ffffffffff', '81eebffffffffff',
+ '81383ffffffffff', '81dcbffffffffff', '81757ffffffffff',
+ '81093ffffffffff', '81073ffffffffff', '8159bffffffffff',
+ '81f17ffffffffff', '81187ffffffffff', '81007ffffffffff',
+ '81997ffffffffff', '81753ffffffffff', '81033ffffffffff',
+ '81f2bffffffffff', '8138bffffffffff',
+ ]
+ mpoly = h3.cells_to_h3shape(cells, tight=False)
+
+ assert len(mpoly) == 1
+ poly = mpoly[0]
+ assert len(poly.holes) == 0
+ assert len(poly.outer) == 128
+
+ # Roundtrip fails: h3shape_to_cells raises on this global polygon.
+ # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons.
+ with pytest.raises(H3FailedError):
+ h3.h3shape_to_cells(mpoly, 1)
+
+
+def test_anti_meridian():
+ """Continuous band of cells overlapping the anti-meridian."""
+ cells = [
+ '817ebffffffffff', '8133bffffffffff', '81047ffffffffff',
+ '81f3bffffffffff', '81dbbffffffffff', '8132bffffffffff',
+ '810cbffffffffff', '81bb3ffffffffff', '81db3ffffffffff',
+ '81bafffffffffff', '81177ffffffffff', '817fbffffffffff',
+ '81ba3ffffffffff', '815abffffffffff', '815bbffffffffff',
+ '81eafffffffffff', '81ed7ffffffffff', '81057ffffffffff',
+ '819a7ffffffffff', '81eabffffffffff', '819b7ffffffffff',
+ '81167ffffffffff', '81227ffffffffff', '8171bffffffffff',
+ '81237ffffffffff', '810dbffffffffff', '81033ffffffffff',
+ '81f2bffffffffff', '8147bffffffffff', '81f33ffffffffff',
+ ]
+ mpoly = h3.cells_to_h3shape(cells, tight=False)
+
+ assert len(mpoly) == 1
+ poly = mpoly[0]
+ assert len(poly.holes) == 0
+ assert len(poly.outer) == 117
+
+ # Roundtrip fails: h3shape_to_cells raises on this global polygon.
+ # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons.
+ with pytest.raises(H3FailedError):
+ h3.h3shape_to_cells(mpoly, 1)
+
+
+def test_issue_482_with_antimeridian():
+ """From https://github.com/uber/h3-py/issues/482
+
+ Test three versions: the full set, removal of antimeridian overlaps, and removal
+ of one cell by the north pole also causing roundtrip issues.
+
+ Roundtrip works after removal of all troublesome cells.
+ """
+ cells0 = {
+ '8001fffffffffff', '8005fffffffffff', '8009fffffffffff', '800bfffffffffff',
+ '8011fffffffffff', '8015fffffffffff', '8017fffffffffff', '801ffffffffffff',
+ '8021fffffffffff', '8025fffffffffff', '802dfffffffffff', '802ffffffffffff',
+ '8031fffffffffff', '8033fffffffffff', '803dfffffffffff', '803ffffffffffff',
+ '8041fffffffffff', '8043fffffffffff', '804bfffffffffff', '804ffffffffffff',
+ '8053fffffffffff', '8059fffffffffff', '8061fffffffffff', '8063fffffffffff',
+ '8065fffffffffff', '8069fffffffffff', '806bfffffffffff', '8073fffffffffff',
+ '8077fffffffffff',
+ }
+
+ # remove cells that overlap the antimeridian
+ cells1 = cells0 - {'8005fffffffffff', '8017fffffffffff', '8033fffffffffff'}
+
+ # remove cell that is very close to north pole (maybe touches)
+ cells2 = cells1 - {'8001fffffffffff'}
+
+ # --- cells0: all 29 cells ---
+ mpoly = h3.cells_to_h3shape(cells0, tight=False)
+ assert len(mpoly) == 1
+ assert len(mpoly[0].holes) == 0
+ assert len(mpoly[0].outer) == 37
+
+ # Roundtrip fails: recovers ~23/29, and not even a subset of the original.
+ # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons.
+ cells_out = h3.h3shape_to_cells(mpoly, 0)
+ assert len(cells_out) < len(cells0) # exact count differs by OS
+ assert not (set(cells_out) <= cells0)
+
+ # --- cells1: remove antimeridian-crossing cells (26 remaining) ---
+ mpoly = h3.cells_to_h3shape(cells1, tight=False)
+ assert len(mpoly) == 1
+ assert len(mpoly[0].holes) == 0
+ assert len(mpoly[0].outer) == 37
+
+ # Roundtrip fails: recovers 18/26, and not even a subset of the original.
+ # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons.
+ cells_out = h3.h3shape_to_cells(mpoly, 0)
+ assert len(cells_out) == 18
+ assert not (set(cells_out) <= cells1)
+
+ # --- cells2: also remove near-pole cell (25 remaining) ---
+ mpoly = h3.cells_to_h3shape(cells2, tight=False)
+ assert len(mpoly) == 1
+ assert len(mpoly[0].holes) == 0
+ assert len(mpoly[0].outer) == 37
+
+ # Roundtrip succeeds.
+ assert_cells_roundtrip(list(cells2))
diff --git a/tests/test_lib/test_apis/test_basic_int.py b/tests/test_lib/test_apis/test_basic_int.py
index a567b3d..3f3b14c 100644
--- a/tests/test_lib/test_apis/test_basic_int.py
+++ b/tests/test_lib/test_apis/test_basic_int.py
@@ -32,3 +32,25 @@ def test_compact_cells():
cells = h3.cell_to_children(h)
assert h3.compact_cells(cells) == [h]
+
+
+def test_identity_scalar_bindings():
+ """
+ Ensure scalar functions in int APIs are bound directly to _cy implementations
+ to eliminate wrapper and identity call overhead (Issue #501).
+ """
+ from h3 import _cy
+
+ assert h3.latlng_to_cell is _cy.latlng_to_cell
+ assert h3.cell_to_parent is _cy.cell_to_parent
+ assert h3.cell_to_center_child is _cy.cell_to_center_child
+ assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge
+ assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin
+ assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination
+ assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells
+ assert h3.local_ij_to_cell is _cy.local_ij_to_cell
+ assert h3.cell_to_vertex is _cy.cell_to_vertex
+
+ # Ensure docstrings and signatures are intact
+ assert h3.latlng_to_cell.__doc__ is not None
+ assert 'latlng_to_cell' in h3.latlng_to_cell.__name__
diff --git a/tests/test_lib/test_apis/test_memview_int.py b/tests/test_lib/test_apis/test_memview_int.py
index 0523794..f608f54 100644
--- a/tests/test_lib/test_apis/test_memview_int.py
+++ b/tests/test_lib/test_apis/test_memview_int.py
@@ -23,3 +23,17 @@ def test_line():
]
assert list(out) == expected
+
+
+def test_identity_scalar_bindings():
+ from h3 import _cy
+
+ assert h3.latlng_to_cell is _cy.latlng_to_cell
+ assert h3.cell_to_parent is _cy.cell_to_parent
+ assert h3.cell_to_center_child is _cy.cell_to_center_child
+ assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge
+ assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin
+ assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination
+ assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells
+ assert h3.local_ij_to_cell is _cy.local_ij_to_cell
+ assert h3.cell_to_vertex is _cy.cell_to_vertex
diff --git a/tests/test_lib/test_apis/test_numpy_int.py b/tests/test_lib/test_apis/test_numpy_int.py
index c341b55..6bcd0b6 100644
--- a/tests/test_lib/test_apis/test_numpy_int.py
+++ b/tests/test_lib/test_apis/test_numpy_int.py
@@ -50,3 +50,17 @@ def test_numpy_str():
got = [h3.str_to_int(c) for c in cells]
assert expected == got
+
+
+def test_identity_scalar_bindings():
+ from h3 import _cy
+
+ assert h3.latlng_to_cell is _cy.latlng_to_cell
+ assert h3.cell_to_parent is _cy.cell_to_parent
+ assert h3.cell_to_center_child is _cy.cell_to_center_child
+ assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge
+ assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin
+ assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination
+ assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells
+ assert h3.local_ij_to_cell is _cy.local_ij_to_cell
+ assert h3.cell_to_vertex is _cy.cell_to_vertex
diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py
index f918019..65d9d13 100644
--- a/tests/test_lib/test_cells_and_edges.py
+++ b/tests/test_lib/test_cells_and_edges.py
@@ -8,6 +8,10 @@ from h3 import (
H3ResMismatchError,
H3CellInvalidError,
H3NotNeighborsError,
+ H3DigitDomainError,
+ H3BaseCellDomainError,
+ H3DeletedDigitError,
+ H3IndexInvalidError,
)
@@ -127,9 +131,7 @@ def test_parent_err():
except Exception as e:
msg = str(e)
- # todo: revist this weird formatting stuff
- expected = 'Invalid parent resolution -1 for cell {}.'
- expected = expected.format(hex(h3.str_to_int(h)))
+ expected = f'Invalid parent resolution -1 for cell 0x{h}.'
assert msg == expected
@@ -452,8 +454,12 @@ def test_versions():
v_c = Version(v['c'])
v_p = Version(v['python'])
- # of X.Y.Z, X and Y must match
- assert v_c.release[:2] == v_p.release[:2]
+ # For all releases (including pre-release), major version must match
+ assert v_c.release[0] == v_p.release[0]
+
+ if not v_p.is_prerelease: # pragma: no cover
+ # of X.Y.Z, X and Y must match
+ assert v_c.release[:2] == v_p.release[:2]
def test_str_int_convert():
@@ -474,6 +480,14 @@ def test_edge_is_valid_fail():
assert not h3.is_valid_directed_edge(e_invalid)
+def test_is_valid_out_of_uint64_range():
+ for h in ['10000000000000000', '-1']:
+ assert not h3.is_valid_index(h)
+ assert not h3.is_valid_cell(h)
+ assert not h3.is_valid_directed_edge(h)
+ assert not h3.is_valid_vertex(h)
+
+
def test_get_pentagons():
out = h3.get_pentagons(0)
@@ -597,3 +611,163 @@ def test_to_local_ij_self():
out = h3.cell_to_local_ij(h, h)
assert out == (-858, -2766)
+
+
+def test_is_valid_index():
+ assert h3.is_valid_index('8001fffffffffff')
+ assert not h3.is_valid_index('8a28308280fffff')
+ assert not h3.is_valid_index(123)
+ assert not h3.is_valid_index('abcd')
+
+
+def test_is_valid_index_2():
+ import h3.api.basic_int as h3
+
+ h = h3.latlng_to_cell(0,0,9)
+ assert h3.is_valid_index(h)
+ assert not h3.is_valid_index(h + 1)
+ assert not h3.is_valid_directed_edge(h)
+ assert not h3.is_valid_vertex(h)
+
+ e = h3.origin_to_directed_edges(h)[0]
+ assert h3.is_valid_index(e)
+ assert not h3.is_valid_index(e + 1)
+ assert not h3.is_valid_cell(e)
+ assert not h3.is_valid_vertex(e)
+
+ v = h3.cell_to_vertex(h, 0)
+ assert h3.is_valid_index(v)
+ assert not h3.is_valid_index(v + 1)
+ assert not h3.is_valid_cell(v)
+ assert not h3.is_valid_directed_edge(v)
+
+
+def test_get_index_digit():
+ assert h3.get_index_digit('822377fffffffff', 1) == 5
+ assert h3.get_index_digit('822377fffffffff', 2) == 6
+ assert h3.get_index_digit('822377fffffffff', 3) == 7
+ assert h3.get_index_digit('822377fffffffff', 15) == 7
+
+ with pytest.raises(H3ResDomainError):
+ h3.get_index_digit('822377fffffffff', 16)
+
+ with pytest.raises(H3ResDomainError):
+ h3.get_index_digit('822377fffffffff', 0)
+
+ with pytest.raises(H3ResDomainError):
+ h3.get_index_digit('822377fffffffff',-1)
+
+
+def test_get_index_digit_non_cells():
+ h = h3.construct_cell(111, 3, 6, 4)
+ assert h == '83def4fffffffff'
+
+ e = h3.origin_to_directed_edges(h)[0]
+ assert e == '113def4fffffffff'
+ assert h3.is_valid_directed_edge(e)
+ assert h3.get_index_digit(e, 1) == 3
+ assert h3.get_index_digit(e, 2) == 6
+ assert h3.get_index_digit(e, 3) == 4
+
+ e = h3.int_to_str(1 + h3.str_to_int(e))
+ assert not h3.is_valid_directed_edge(e)
+ assert not h3.is_valid_index(e)
+ with pytest.raises(H3IndexInvalidError):
+ h3.get_index_digit(e, 1)
+
+ v = h3.cell_to_vertexes(h)[0]
+ assert v == '223de1afffffffff'
+ assert h3.is_valid_vertex(v)
+ assert h3.get_index_digit(v, 1) == 0
+ assert h3.get_index_digit(v, 2) == 3
+ assert h3.get_index_digit(v, 3) == 2
+
+ v = h3.int_to_str(1 + h3.str_to_int(v))
+ assert not h3.is_valid_vertex(v)
+ assert not h3.is_valid_index(v)
+ with pytest.raises(H3IndexInvalidError):
+ h3.get_index_digit(v, 1)
+
+
+def test_construct_cell():
+ bc = 17
+ assert h3.construct_cell(bc, 5, 6) == '822377fffffffff'
+ assert h3.construct_cell(bc) == '8023fffffffffff'
+
+ digits = [0] * 15
+ assert h3.construct_cell(bc, *digits) == '8f2200000000000'
+
+ with pytest.raises(H3ResDomainError):
+ digits = [0] * 16
+ h3.construct_cell(bc, *digits)
+
+ with pytest.raises(ValueError):
+ digits = [1,2,3,4]
+ h3.construct_cell(bc, *digits, res=2)
+
+ with pytest.raises(H3DigitDomainError):
+ h3.construct_cell(121, 1, 7) # 7 is not a valid digit
+
+ with pytest.raises(H3DigitDomainError):
+ h3.construct_cell(121, 45) # 45 is not a valid digit
+
+ with pytest.raises(H3DigitDomainError):
+ h3.construct_cell(121, -1) # -1 is not a valid digit
+
+ with pytest.raises(H3BaseCellDomainError):
+ h3.construct_cell(122) # one past last base cell number
+
+ with pytest.raises(H3DeletedDigitError):
+ # 4 is a pentagon base cell. first nonzero digit can't be a 1
+ h3.construct_cell(4, 1)
+
+ with pytest.raises(H3DeletedDigitError):
+ # 4 is a pentagon base cell. first nonzero digit can't be a 1
+ h3.construct_cell(4, 0,0,0, 0, 1)
+
+
+def test_deconstruct_cell():
+ h = '822377fffffffff'
+ assert h3.deconstruct_cell(h) == [17, 5, 6]
+
+
+def test_construct_cell_inverses():
+ # demonstrate functions are inverses of each other
+
+ h = '8ff3ac688d63446'
+ components = [121, 6, 5, 4, 3, 2, 1, 0, 6, 5, 4, 3, 2, 1, 0, 6]
+
+ assert h3.construct_cell(*components) == h
+ assert h3.deconstruct_cell(h) == components
+
+ assert h3.construct_cell(*h3.deconstruct_cell(h)) == h
+ assert h3.deconstruct_cell(h3.construct_cell(*components)) == components
+
+
+def test_construct_cell_inverses_int_api():
+ # same inverse test as above, but in int api
+ import h3.api.basic_int as h3
+
+ h = 0x8ff3ac688d63446
+ components = [121, 6, 5, 4, 3, 2, 1, 0, 6, 5, 4, 3, 2, 1, 0, 6]
+
+ assert h3.construct_cell(*components) == h
+ assert h3.deconstruct_cell(h) == components
+
+ assert h3.construct_cell(*h3.deconstruct_cell(h)) == h
+ assert h3.deconstruct_cell(h3.construct_cell(*components)) == components
+
+
+def test_center_child_with_deconstruct():
+ for h in h3.get_res0_cells():
+ h3.construct_cell(*h3.deconstruct_cell(h), 0) == h3.cell_to_center_child(h)
+
+
+def test_uncompact_cells_invalid_resolution():
+ # Create a valid cell at resolution 5
+ h_res5 = h3.latlng_to_cell(0, 0, 5)
+
+ # Attempting to uncompact to a coarser resolution (4)
+ # should raise an H3ResMismatchError
+ with pytest.raises(H3ResMismatchError):
+ h3.uncompact_cells({h_res5}, 4)
diff --git a/tests/test_lib/test_error_codes.py b/tests/test_lib/test_error_codes.py
index 9961178..4ae1d37 100644
--- a/tests/test_lib/test_error_codes.py
+++ b/tests/test_lib/test_error_codes.py
@@ -1,6 +1,10 @@
import pytest
import h3
+from h3._cy import (
+ error_code_to_exception,
+ get_H3_ERROR_END,
+)
# todo: maybe check the `check_for_error` function behavior directly?
@@ -12,24 +16,30 @@ h3_exceptions = {
h3.H3GridNavigationError: None,
h3.H3MemoryError: None,
h3.H3ValueError: None,
-
- h3.H3FailedError: 1,
- h3.H3DomainError: 2,
- h3.H3LatLngDomainError: 3,
- h3.H3ResDomainError: 4,
- h3.H3CellInvalidError: 5,
- h3.H3DirEdgeInvalidError: 6,
- h3.H3UndirEdgeInvalidError: 7,
- h3.H3VertexInvalidError: 8,
- h3.H3PentagonError: 9,
- h3.H3DuplicateInputError: 10,
- h3.H3NotNeighborsError: 11,
- h3.H3ResMismatchError: 12,
- h3.H3MemoryAllocError: 13,
- h3.H3MemoryBoundsError: 14,
- h3.H3OptionInvalidError: 15,
}
+for e in range(1, get_H3_ERROR_END()):
+ ex = error_code_to_exception(e)
+ h3_exceptions[ex] = e
+
+
+def test_num_error_codes():
+ assert get_H3_ERROR_END() >= 20
+ assert error_code_to_exception(19) == h3.H3DeletedDigitError
+
+ # H3_ERROR_END (and beyond) shouldn't be a valid error code
+ code = get_H3_ERROR_END()
+ assert isinstance(
+ error_code_to_exception(code),
+ h3.UnknownH3ErrorCode
+ )
+
+ code = get_H3_ERROR_END() + 1
+ assert isinstance(
+ error_code_to_exception(code),
+ h3.UnknownH3ErrorCode
+ )
+
def test_error_codes_match():
"""
diff --git a/tests/test_lib/test_geojson_containers.py b/tests/test_lib/test_geojson_containers.py
new file mode 100644
index 0000000..a890c27
--- /dev/null
+++ b/tests/test_lib/test_geojson_containers.py
@@ -0,0 +1,62 @@
+import pytest
+from h3._h3shape import LatLngPoly, h3shape_to_geo, LatLngMultiPoly
+
+
+def test_h3shape_to_geo_containers():
+ # Create a basic dummy polygon for testing
+ poly = LatLngPoly(
+ [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)]
+ )
+
+ # Test 'auto' (Default behavior should return a Polygon)
+ auto_geo = h3shape_to_geo(poly, container='auto')
+ assert auto_geo['type'] == 'Polygon'
+
+ # Test MultiPolygon wrapper
+ mp_geo = h3shape_to_geo(poly, container='MultiPolygon')
+ assert mp_geo['type'] == 'MultiPolygon'
+ assert len(mp_geo['coordinates']) == 1
+
+ # Test Feature wrapper
+ feat_geo = h3shape_to_geo(poly, container='Feature')
+ assert feat_geo['type'] == 'Feature'
+ assert feat_geo['geometry']['type'] == 'Polygon'
+
+ # Test FeatureCollection wrapper
+ fc_geo = h3shape_to_geo(poly, container='FeatureCollection')
+ assert fc_geo['type'] == 'FeatureCollection'
+ assert len(fc_geo['features']) == 1
+ assert fc_geo['features'][0]['type'] == 'Feature'
+ assert fc_geo['features'][0]['geometry']['type'] == 'Polygon'
+
+ # Test GeometryCollection wrapper
+ gc_geo = h3shape_to_geo(poly, container='GeometryCollection')
+ assert gc_geo['type'] == 'GeometryCollection'
+ assert len(gc_geo['geometries']) == 1
+ assert gc_geo['geometries'][0]['type'] == 'Polygon'
+
+
+def test_h3shape_to_geo_invalid_containers():
+ # 1. Test an unknown container string
+ poly = LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)])
+ with pytest.raises(ValueError, match='invalid or insufficient'):
+ h3shape_to_geo(poly, container='InvalidString')
+
+ # 2. Test an insufficient container (MultiPolygon data into a Polygon container)
+ mpoly = LatLngMultiPoly(
+ LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)])
+ )
+ with pytest.raises(ValueError, match='invalid or insufficient'):
+ h3shape_to_geo(mpoly, container='Polygon')
+
+
+def test_h3shape_to_geo_exact_match():
+ # Test that requesting a MultiPolygon for MultiPolygon data succeeds
+ mpoly = LatLngMultiPoly(
+ LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)])
+ )
+
+ mp_geo = h3shape_to_geo(mpoly, container='MultiPolygon')
+
+ assert mp_geo['type'] == 'MultiPolygon'
+ assert len(mp_geo['coordinates']) == 1
diff --git a/tests/test_lib/test_length_area.py b/tests/test_lib/test_length_area.py
index 1003f56..ca38257 100644
--- a/tests/test_lib/test_length_area.py
+++ b/tests/test_lib/test_length_area.py
@@ -86,6 +86,30 @@ def test_areas_at_00():
assert u.approx2(out, areas_rads2)
+def test_average_hexagon_area_rads():
+ # the ratio between km^2 and rads^2 should match the one used by cell_area
+ h = '89754e64993ffff'
+ ratio = h3.cell_area(h, unit='km^2') / h3.cell_area(h, unit='rads^2')
+
+ for res in range(16):
+ km2 = h3.average_hexagon_area(res, unit='km^2')
+ rads2 = h3.average_hexagon_area(res, unit='rads^2')
+
+ assert km2 / rads2 == pytest.approx(ratio)
+
+
+def test_average_hexagon_edge_length_rads():
+ # the ratio between km and rads should match the one used by edge_length
+ e = '139754e64993ffff'
+ ratio = h3.edge_length(e, unit='km') / h3.edge_length(e, unit='rads')
+
+ for res in range(16):
+ km = h3.average_hexagon_edge_length(res, unit='km')
+ rads = h3.average_hexagon_edge_length(res, unit='rads')
+
+ assert km / rads == pytest.approx(ratio)
+
+
def test_bad_units():
h = '89754e64993ffff'
e = '139754e64993ffff'