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 1101c15..8cb052b 100644 --- a/readme.md +++ b/readme.md @@ -1,15 +1,15 @@ -# **h3-py**: Uber's H3 Hexagonal Hierarchical Geospatial Indexing System in Python +H3 Logo -H3 Logo +# **h3-py**: Uber's H3 Hexagonal Hierarchical Geospatial Indexing System in Python [![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3) [![PyPI downloads](https://img.shields.io/pypi/dm/h3.svg)](https://pypistats.org/packages/h3) [![conda](https://img.shields.io/conda/vn/conda-forge/h3-py.svg)](https://anaconda.org/conda-forge/h3-py) -[![version](https://img.shields.io/badge/h3-v4.1.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.1.0) +[![version](https://img.shields.io/badge/h3-v4.5.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.5.0) [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE) [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) -[![codecov](https://codecov.io/gh/uber/h3-py/branch/master/graph/badge.svg)](https://codecov.io/gh/uber/h3-py) +[![Coverage 100%](https://img.shields.io/badge/coverage-100%25-green.svg)](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'