diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 9cc00a2..f6c950c 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@v6.0.2 + - uses: actions/checkout@v4.2.2 with: submodules: recursive - - uses: astral-sh/setup-uv@v7 + - uses: actions/setup-python@v5.3.0 with: - python-version: '3.11' + python-version: 3.11 - - uses: extractions/setup-just@v2 + - name: Install dependencies + run: | + pip install --upgrade pip setuptools wheel + pip install .[all] - name: Build the book - run: just docs + run: jupyter-book build docs/ --warningiserror --keep-going --all - name: Upload artifacts - uses: actions/upload-artifact@v6.0.0 + uses: actions/upload-artifact@v4.4.3 with: name: html path: docs/_build/html diff --git a/.github/workflows/lint_and_coverage.yml b/.github/workflows/lint_and_coverage.yml index 8ec1ef1..395b38b 100644 --- a/.github/workflows/lint_and_coverage.yml +++ b/.github/workflows/lint_and_coverage.yml @@ -6,33 +6,28 @@ on: pull_request: branches: ['*'] -permissions: - contents: read - jobs: linting: name: Lint and Coverage runs-on: ubuntu-24.04 steps: - - uses: actions/checkout@v6.0.2 + - uses: actions/checkout@v4 with: submodules: recursive - - uses: astral-sh/setup-uv@v7 + - uses: actions/setup-python@v5 with: - python-version: '3.11' + python-version: 3.11 - - uses: extractions/setup-just@v2 + - name: Install from source + run: pip install .[test] - - name: Lint - run: just lint + - name: Run Linting + uses: astral-sh/ruff-action@v3 - - name: Install - run: uv sync - - - name: Coverage - Library - run: just ci-test - - - name: Coverage - Cython - run: just ci-test-cython + - name: Coverage Requirement + run: | + pip install cython + cythonize tests/test_cython/cython_example.pyx + pytest --cov-fail-under=99 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index f7a9854..cd4153d 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,19 +14,17 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-22.04] - python-version: ['3.10', '3.11', '3.12', '3.13', '3.14', '3.14t', '3.15', '3.15t'] + python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13'] steps: - - uses: actions/checkout@v6.0.2 + - uses: actions/checkout@v4.2.2 with: submodules: recursive - - uses: astral-sh/setup-uv@v7 + - uses: actions/setup-python@v5.3.0 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') @@ -38,11 +36,13 @@ jobs: echo "CXX=cl.exe" >> $GITHUB_ENV ## End Windows stuff - - name: Install - run: uv sync + - name: Install from source + run: | + pip install --upgrade pip setuptools wheel + pip install .[test] - name: Tests - run: just ci-test - - - name: Cython Tests - run: just ci-test-cython + run: | + pip install cython + cythonize tests/test_cython/cython_example.pyx + pytest diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 1de5a80..c70b891 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@v6.0.2 + - uses: actions/checkout@v4.2.2 with: submodules: recursive - - uses: astral-sh/setup-uv@v7 + - name: Setup Python + uses: actions/setup-python@v5.3.0 with: - python-version: '3.11' - + python-version: 3.11 - name: Make sdist - run: uv build --sdist + run: | + python --version + pipx --version + pipx run 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: | - uv venv + pip install --upgrade pip setuptools wheel cp dist/h3-*.tar.gz h3.tar.gz - uv pip install h3.tar.gz[numpy] pytest pytest-cov + pip install h3.tar.gz[test] - name: Test sdist - # run pytest directly from the venv to avoid `uv run` syncing from the local checkout - run: .venv/bin/pytest + run: pytest - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v6.0.0 + uses: actions/upload-artifact@v4.4.3 with: name: temp_result_sdist path: ./dist @@ -60,40 +60,27 @@ jobs: strategy: matrix: include: - - os: macos-15 + - os: macos-13 + build: 'cp*-macosx_x86_64' + name: macOS13 + - os: macos-14 build: 'cp*-macosx_arm64' - name: macOS15 + name: macOS14 - 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 @@ -106,19 +93,13 @@ 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 @@ -131,37 +112,14 @@ 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@v6.0.2 + - uses: actions/checkout@v4.2.2 with: submodules: recursive - - 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 + - uses: ilammy/msvc-dev-cmd@v1.13.0 + if: runner.os == 'Windows' - name: Set Windows variables if: runner.os == 'Windows' @@ -172,23 +130,23 @@ jobs: - name: Set up QEMU if: runner.os == 'Linux' - uses: docker/setup-qemu-action@v3.7.0 + uses: docker/setup-qemu-action@v3.2.0 with: platforms: aarch64 - - uses: pypa/cibuildwheel@v4.2.1 + - uses: pypa/cibuildwheel@v2.21.3 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: uvx twine check wheelhouse/* + run: | + pipx run twine check wheelhouse/* - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v6.0.0 + uses: actions/upload-artifact@v4.4.3 with: name: temp_result_${{ matrix.os }}-${{ strategy.job-index }} path: wheelhouse/*.whl @@ -198,7 +156,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Merge Artifacts - uses: actions/upload-artifact/merge@v6 + uses: actions/upload-artifact/merge@v4.4.3 with: name: wheels_and_sdist pattern: temp_result_* @@ -206,35 +164,17 @@ jobs: retention-days: 7 compression-level: 9 - check_merged: - needs: [merge] - runs-on: ubuntu-latest - steps: - - 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 - - - name: Check all wheels and sdist with Twine - run: uvx twine check dist/* - to_pypi: - needs: [check_merged] + needs: [merge] if: github.event_name == 'release' && github.event.action == 'published' runs-on: ubuntu-latest steps: - - uses: actions/download-artifact@v7.0.0 + - uses: actions/download-artifact@v4.1.8 with: name: wheels_and_sdist path: dist - - uses: pypa/gh-action-pypi-publish@v1.13.0 + - uses: pypa/gh-action-pypi-publish@v1.10.3 with: password: ${{ secrets.pypi_password }} diff --git a/.gitignore b/.gitignore index 1141de9..ad8e4f3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,57 +1,74 @@ -# Byte-compiled / optimized +h3c/ *.py[cod] -__pycache__/ - -# C extensions -*.so +.cache/ +h3/out/ +.ruff_cache/ # Generated C code from Cython test tests/**/*.c # Cython HTML annotations *.html -# Build artifacts -build/ -dist/ -*.egg-info +# C extensions +*.so -# Coverage +# Packages +*.egg +*.egg-info +dist +build +eggs +parts +bin +var +sdist +develop-eggs +.installed.cfg + +# Installer logs +pip-log.txt + +# Unit test / coverage reports .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/ -# Test -.pytest_cache/ - -# Tools -.ruff_cache/ -.cache/ - -# Docs -_build/ -docs/_build/ - -# Environment -.venv/ -uv.lock - -# OS -.DS_Store - -# Editor backup files +# vim/emacs backup files *~ \#*\# .\#* .*.sw* -# IDE +#DB snapshots +db_snapshots/ + +#OSX +.DS_Store + +node_modules/ +bower_components/ +.sass-cache/ .idea/ +.unison.* -# IPython / Jupyter .ipynb_checkpoints/ - -# Legacy build dirs _skbuild/ -h3c/ -h3/out/ + +# might want to remove this later when distributing +MANIFEST diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b6ee3a..4c60e19 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,85 +15,8 @@ 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) -## [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 +- Update to v4.2.0. (#432) ## [4.1.2] - 2024-10-26 @@ -166,7 +89,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 52a76f1..40ce38e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,16 +1,5 @@ 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 65b4f62..71d514d 100644 --- a/dev_notes.md +++ b/dev_notes.md @@ -2,21 +2,11 @@ ## Install for development -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` +- `git clone git@github.com:uber/h3-py.git` - `cd h3-py` -- `just lint` -- `just test` -- `just test-cython` - -To build and view docs: - -- `just docs` -- `just view` +- `make init` +- `make test` +- `make lint` ## Docstrings @@ -59,7 +49,6 @@ 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 6694ed4..5503bae 100644 --- a/docs/api_quick.md +++ b/docs/api_quick.md @@ -25,7 +25,6 @@ and should be generally aligned with the is_res_class_III is_valid_directed_edge is_valid_vertex - is_valid_index ``` ## Index representation @@ -50,9 +49,6 @@ 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 @@ -165,17 +161,6 @@ Note that this is reversed from [``__geo_interface__``](https://gist.github.com/ cells_to_geo ``` -#### Additional functions - -```{eval-rst} -.. currentmodule:: h3 - -.. autosummary:: - polygon_to_cells - polygon_to_cells_experimental - h3shape_to_cells_experimental -``` - ## Specialized functions diff --git a/justfile b/justfile deleted file mode 100644 index d8e44fb..0000000 --- a/justfile +++ /dev/null @@ -1,61 +0,0 @@ -# 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 new file mode 100644 index 0000000..eabc213 --- /dev/null +++ b/makefile @@ -0,0 +1,50 @@ +.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/pip install cython + ./env/bin/cythonize tests/test_cython/cython_example.pyx + ./env/bin/pytest --cov-fail-under=99 + +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 4430799..93cb37d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.5.0' +version = '4.2.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.10' +requires-python = '>=3.8' dependencies = [] @@ -25,13 +25,12 @@ 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', @@ -39,21 +38,19 @@ classifiers = [ ] [project.urls] -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' +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' [project.optional-dependencies] numpy = ['numpy'] - -[dependency-groups] -dev = ['pytest', 'pytest-cov', 'numpy'] -docs = [ - 'numpy', - 'jupyter-book<2', +test = ['pytest', 'pytest-cov', 'ruff', 'numpy'] +all = [ + 'h3[test]', + 'jupyter-book', 'sphinx>=7.3.3', # https://github.com/sphinx-doc/sphinx/issues/12290 'jupyterlab', 'jupyterlab-geojson', @@ -66,7 +63,7 @@ docs = [ ] [tool.pytest.ini_options] -addopts = "--cov-report=term-missing --durations=10" +addopts = "--cov=h3 --cov=tests --cov-report=term-missing --durations=10" [tool.coverage.run] omit = [ @@ -76,25 +73,18 @@ omit = [ ] -[tool.uv] -default-groups = ['dev'] - [tool.scikit-build] sdist.exclude = [ 'src/h3lib', 'docs', 'dev_notes.md', - 'justfile', - '.github', - '.gitignore', - '.gitmodules', + 'makefile', ] 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 8cb052b..cb36c71 100644 --- a/readme.md +++ b/readme.md @@ -1,15 +1,29 @@ -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.5.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.5.0) +[![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/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) -[![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) +[![codecov](https://codecov.io/gh/uber/h3-py/branch/master/graph/badge.svg)](https://codecov.io/gh/uber/h3-py) + + +---- +## ANNOUNCEMENT: v4.1 final released on 2024-10-13! + +Feedback is welcome via +[Issues](https://github.com/uber/h3-py/issues/new), +[Discussions](https://github.com/uber/h3/discussions), +and +[Slack](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg). + +---- Python bindings for the [H3 core library](https://h3geo.org/). diff --git a/src/h3/__init__.py b/src/h3/__init__.py index 1e4f4b8..4f7cb32 100644 --- a/src/h3/__init__.py +++ b/src/h3/__init__.py @@ -26,8 +26,4 @@ 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 70fa087..627f3b9 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -14,13 +14,10 @@ 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, @@ -112,11 +109,4 @@ 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 1bc31b8..06b35ee 100644 --- a/src/h3/_cy/cells.pxd +++ b/src/h3/_cy/cells.pxd @@ -1,12 +1,9 @@ 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 f0667e5..2b57af2 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -1,17 +1,13 @@ -# cython: freethreading_compatible=True cimport h3lib from .h3lib cimport bool, int64_t, H3int, H3ErrorCodes from .util cimport ( check_cell, - check_index, + check_res, # we don't use? check_distance, ) -from .util import EARTH_RADIUS_KM - from .error_system cimport ( - H3Error, check_for_error, check_for_error_msg, ) @@ -23,14 +19,6 @@ 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): @@ -61,33 +49,6 @@ 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 @@ -126,6 +87,41 @@ 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. @@ -135,10 +131,11 @@ cpdef H3int[:] grid_ring(H3int h, int k): n = 6*k if k > 0 else 1 hmm = H3MemoryManager(n) - check_for_error( - h3lib.gridRing(h, k, hmm.ptr) - ) - mv = hmm.to_mv() + err = h3lib.gridRingUnsafe(h, k, hmm.ptr) + if err: + mv = _ring_fallback(h, k) + else: + mv = hmm.to_mv() return mv @@ -324,8 +321,7 @@ 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, - 'rads^2': 1.0/(EARTH_RADIUS_KM*EARTH_RADIUS_KM), + 'm^2': 1000*1000.0 } try: diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index 7364bd5..bd0aa7c 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -1,11 +1,8 @@ -# 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 @@ -88,8 +85,7 @@ cpdef double average_hexagon_edge_length(int resolution, unit='km') except -1: # todo: multiple units convert = { 'km': 1.0, - 'm': 1000.0, - 'rads': 1.0/EARTH_RADIUS_KM, + 'm': 1000.0 } try: diff --git a/src/h3/_cy/error_system.pxd b/src/h3/_cy/error_system.pxd index 4a1e3b4..af8c709 100644 --- a/src/h3/_cy/error_system.pxd +++ b/src/h3/_cy/error_system.pxd @@ -1,6 +1,3 @@ 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 5fe5cd9..fbdd918 100644 --- a/src/h3/_cy/error_system.pyx +++ b/src/h3/_cy/error_system.pyx @@ -1,4 +1,3 @@ -# cython: freethreading_compatible=True """ Exceptions from the h3-py library have three possible sources: @@ -61,10 +60,6 @@ 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 @@ -92,11 +87,6 @@ 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 @@ -179,10 +169,6 @@ 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): ... """ @@ -206,10 +192,6 @@ 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 @@ -225,37 +207,25 @@ for code, ex in error_mapping.items(): # TODO: Move the helpers to util? # TODO: Unclear how/where to expose these functions. cdef/cpdef? -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. - """ +cdef code_to_exception(H3Error err): if err == E_SUCCESS: return None elif err in error_mapping: return error_mapping[err] else: - return UnknownH3ErrorCode(err) + raise UnknownH3ErrorCode(err) cdef check_for_error(H3Error err): - ex = error_code_to_exception(err) + ex = 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 = error_code_to_exception(err) + ex = code_to_exception(err) if ex: raise ex(msg) diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 6ee3b41..4a483b2 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -29,11 +29,6 @@ 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 @@ -47,6 +42,21 @@ 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 @@ -61,15 +71,12 @@ 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 @@ -132,7 +139,6 @@ 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 @@ -156,15 +162,18 @@ 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) @@ -181,11 +190,3 @@ 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 630d3ad..60b9053 100644 --- a/src/h3/_cy/latlng.pyx +++ b/src/h3/_cy/latlng.pyx @@ -1,4 +1,3 @@ -# cython: freethreading_compatible=True from libc.stdint cimport uint64_t cimport h3lib @@ -197,7 +196,7 @@ def polygons_to_cells(polygons, int res): return hmm.to_mv() -def polygon_to_cells_experimental(outer, int res, int flag, holes=None): +def polygon_to_cells_experimental(outer, int res, int flags, holes=None): """ Get the set of cells whose center is contained in a polygon. The polygon is defined similarity to the GeoJson standard, with an exterior @@ -222,8 +221,8 @@ def polygon_to_cells_experimental(outer, int res, int flag, holes=None): A ring given by a sequence of lat/lng pairs. res : int The resolution of the output hexagons - flag : int - Polygon to cells flag, such as containment mode. + flags : int + Polygon to cells flags, such as containment mode. holes : list or tuple A collection of rings, each given by a sequence of lat/lng pairs. These describe any the "holes" in the polygon. @@ -239,21 +238,21 @@ def polygon_to_cells_experimental(outer, int res, int flag, holes=None): gp = GeoPolygon(outer, holes=holes) check_for_error( - h3lib.maxPolygonToCellsSizeExperimental(&gp.gp, res, flag, &n) + h3lib.maxPolygonToCellsSizeExperimental(&gp.gp, res, flags, &n) ) hmm = H3MemoryManager(n) check_for_error( - h3lib.polygonToCellsExperimental(&gp.gp, res, flag, n, hmm.ptr) + h3lib.polygonToCellsExperimental(&gp.gp, res, flags, n, hmm.ptr) ) mv = hmm.to_mv() return mv -def polygons_to_cells_experimental(polygons, int res, int flag): +def polygons_to_cells_experimental(polygons, int res, int flags): mvs = [ - polygon_to_cells_experimental(outer=poly.outer, res=res, holes=poly.holes, flag=flag) + polygon_to_cells_experimental(outer=poly.outer, res=res, holes=poly.holes, flags=flags) for poly in polygons ] @@ -262,15 +261,11 @@ 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: - if v not in seen: - seen.add(v) - hmm.ptr[k] = v - k += 1 + 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 963b00d..0852105 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -1,4 +1,3 @@ -# 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 cb5e5e2..db29baa 100644 --- a/src/h3/_cy/to_multipoly.pyx +++ b/src/h3/_cy/to_multipoly.pyx @@ -1,46 +1,60 @@ -# cython: freethreading_compatible=True cimport h3lib from h3lib cimport H3int from .util cimport check_cell, coord2deg -from .error_system cimport check_for_error -cdef _loop_to_list(const h3lib.GeoLoop *loop): - return [coord2deg(loop.verts[v]) for v in range(loop.numVerts)] +# 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 _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_loops(const h3lib.LinkedGeoLoop* L): + out = [] + while L: + out += [walk_coords(L.data)] + L = L.next + + return out +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.GeoMultiPolygon mpoly - H3int cell + h3lib.LinkedGeoPolygon polygon - for cell in cells: - check_cell(cell) + for h in cells: + check_cell(h) - check_for_error( - h3lib.cellsToMultiPolygon(&cells[0], len(cells), &mpoly) - ) + h3lib.cellsToLinkedMultiPolygon(&cells[0], len(cells), &polygon) - try: - out = [ - _poly_to_lists(&mpoly.polygons[p]) - for p in range(mpoly.numPolygons) - ] - finally: - h3lib.destroyGeoMultiPolygon(&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) 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 [] - return _to_multi_polygon(cells) + multipoly = _to_multi_polygon(cells) + + return multipoly diff --git a/src/h3/_cy/util.pxd b/src/h3/_cy/util.pxd index b584d3a..4d7d962 100644 --- a/src/h3/_cy/util.pxd +++ b/src/h3/_cy/util.pxd @@ -8,7 +8,6 @@ cpdef H3str int_to_str(H3int x) cdef check_cell(H3int h) cdef check_edge(H3int e) -cdef check_vertex(H3int v) -cdef check_index(H3int h) cdef check_res(int res) +cdef check_vertex(H3int v) cdef check_distance(int k) diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 74e8f80..7b8a9f2 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -1,12 +1,4 @@ -# cython: freethreading_compatible=True -from .h3lib cimport ( - H3int, - H3str, - isValidCell, - isValidDirectedEdge, - isValidVertex, - isValidIndex, -) +from .h3lib cimport H3int, H3str, isValidCell, isValidDirectedEdge, isValidVertex cimport h3lib @@ -15,14 +7,9 @@ from .error_system import ( H3DomainError, H3DirEdgeInvalidError, H3CellInvalidError, - H3VertexInvalidError, - H3IndexInvalidError, + H3VertexInvalidError ) -# 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 @@ -91,10 +78,6 @@ 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 99cc5ef..26a674a 100644 --- a/src/h3/_cy/vertex.pyx +++ b/src/h3/_cy/vertex.pyx @@ -1,4 +1,3 @@ -# cython: freethreading_compatible=True cimport h3lib from h3lib cimport bool, H3int diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 68d18c2..261dfa9 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -1,4 +1,15 @@ from abc import ABCMeta, abstractmethod +from enum import Enum + + +class ContainmentMode(int, Enum): + """ + Containment modes for use with ``polygon_to_cells_experimental``. + """ + containment_center = 0 + containment_full = 1 + containment_overlapping = 2 + containment_overlapping_bbox = 3 class H3Shape(metaclass=ABCMeta): @@ -54,7 +65,7 @@ class LatLngPoly(H3Shape): def __init__(self, outer, *holes): loops = [outer] + list(holes) for loop in loops: - if len(loop) > 0 and len(_open_ring(loop)) < 3: + if len(loop) in (1, 2): raise ValueError('Non-empty LatLngPoly loops need at least 3 points.') point_dimensions = set(map(len, loop)) @@ -184,6 +195,13 @@ 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, ... """ @@ -223,10 +241,6 @@ 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 @@ -305,11 +319,7 @@ def geo_to_h3shape(geo): # get dict geo = geo.__geo_interface__ - if not isinstance(geo, dict): - raise ValueError( - 'geo must be a dict or implement __geo_interface__, got: ' - + str(type(geo)) - ) + assert isinstance(geo, dict) # todo: remove t = geo['type'] coord = geo['coordinates'] @@ -326,63 +336,14 @@ def geo_to_h3shape(geo): return shape -def h3shape_to_geo(h3shape, container='auto'): +def h3shape_to_geo(h3shape): """ 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 """ - 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']}'." - ) + return h3shape.__geo_interface__ diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 8eac4b1..cf450c8 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -1,9 +1,8 @@ # 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 ( + ContainmentMode, H3Shape, LatLngPoly, LatLngMultiPoly, @@ -129,20 +128,6 @@ 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). @@ -154,13 +139,13 @@ def is_valid_cell(h): try: h = _in_scalar(h) return _cy.is_valid_cell(h) - except (ValueError, TypeError, OverflowError): + except (ValueError, TypeError): return False def is_valid_directed_edge(edge): """ - Validates an H3 directed edge. + Validates an H3 unidirectional edge. Returns ------- @@ -169,7 +154,7 @@ def is_valid_directed_edge(edge): try: e = _in_scalar(edge) return _cy.is_valid_directed_edge(e) - except (ValueError, TypeError, OverflowError): + except (ValueError, TypeError): return False @@ -474,6 +459,8 @@ 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) @@ -481,13 +468,6 @@ def uncompact_cells(cells, res): return _out_collection(hu) -def polygon_to_cells(h3shape, res): - """ - Alias for ``h3shape_to_cells``. - """ - return h3shape_to_cells(h3shape, res) - - def h3shape_to_cells(h3shape, res): """ Return the collection of H3 cells at a given resolution whose center points @@ -539,46 +519,25 @@ def h3shape_to_cells(h3shape, res): return _out_collection(mv) -def polygon_to_cells_experimental( - h3shape: H3Shape, - res: int, - contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', -): +def polygon_to_cells(h3shape, res): """ - Alias for ``h3shape_to_cells_experimental``. + Alias for ``h3shape_to_cells``. """ - return h3shape_to_cells_experimental(h3shape, res, contain) + return h3shape_to_cells(h3shape, res) -def h3shape_to_cells_experimental( - h3shape: H3Shape, - res: int, - contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', -): +def h3shape_to_cells_experimental(h3shape, res, flags=0): """ - Experimental function similar to ``h3shape_to_cells``, but with support for - multiple cell containment modes. - - Using ``contain='center'`` should give identical behavior as - ``h3shape_to_cells``. - - Note that this function is **experimental** and has no API stability gaurantees - across versions, so it may change in the future. - + Return the collection of H3 cells at a given resolution whose center points + are contained within an ``LatLngPoly`` or ``LatLngMultiPoly``. Parameters ---------- h3shape : ``H3Shape`` res : int Resolution of the output cells - contain : {'center', 'full', 'overlap', 'bbox_overlap'}, optional - Specifies the containment condition. - - 'center': Cell center is contained in shape - - 'full': Cell is fully contained in shape - - 'overlap': Cell is partially contained in shape - - 'bbox_overlap': Cell bounding box is partially contained in shape - - Default is 'center'. + flags : ``ContainmentMode``, int, or string + Containment mode flags Returns ------- @@ -591,7 +550,7 @@ def h3shape_to_cells_experimental( ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), ... (37.82, -122.54)], ... ) - >>> h3.h3shape_to_cells_experimental(poly, 6, 'center') + >>> h3.h3shape_to_cells_experimental(poly, 6, h3.ContainmentMode.containment_center) ['862830807ffffff', '862830827ffffff', '86283082fffffff', @@ -605,27 +564,30 @@ def h3shape_to_cells_experimental( There is currently no guaranteed order of the output cells. """ - contain_modes = { - 'center': 0, - 'full': 1, - 'overlap': 2, - 'bbox_overlap': 3, - } - - flag = contain_modes[contain] + if isinstance(flags, str): + try: + flags = ContainmentMode[flags] + except KeyError as e: + raise ValueError('Unrecognized flags: ' + flags) from e + if isinstance(flags, ContainmentMode): + flags = int(flags) + if not isinstance(flags, int): + raise ValueError( + 'Flags should be ContainmentMode, str, or int, but got: ' + str(type(flags)) + ) # todo: not sure if i want this dispatch logic here. maybe in the objects? if isinstance(h3shape, LatLngPoly): poly = h3shape mv = _cy.polygon_to_cells_experimental( poly.outer, - res = res, - holes = poly.holes, - flag = flag, + res=res, + holes=poly.holes, + flags=flags ) elif isinstance(h3shape, LatLngMultiPoly): mpoly = h3shape - mv = _cy.polygons_to_cells_experimental(mpoly.polys, res=res, flag=flag) + mv = _cy.polygons_to_cells_experimental(mpoly.polys, res=res, flags=flags) elif isinstance(h3shape, H3Shape): raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) else: @@ -634,6 +596,13 @@ def h3shape_to_cells_experimental( return _out_collection(mv) +def polygon_to_cells_experimental(h3shape, res, flags=0): + """ + Alias for ``h3shape_to_cells_experimental``. + """ + return h3shape_to_cells_experimental(h3shape, res, flags=flags) + + def cells_to_h3shape(cells, *, tight=True): """ Return an ``H3Shape`` describing the area covered by a collection of H3 cells. @@ -749,124 +718,10 @@ 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. @@ -1363,30 +1218,5 @@ def is_valid_vertex(v): try: v = _in_scalar(v) return _cy.is_valid_vertex(v) - except (ValueError, TypeError, OverflowError): + except (ValueError, TypeError): 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 1b536c3..2d8a62d 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit 1b536c34225191ba24a75a840f634d4a48c3b206 +Subproject commit 2d8a62d5fe456bba2af7ca0be7efe9754f1dd25b diff --git a/tests/test_lib/__init__.py b/tests/__init__.py similarity index 100% rename from tests/test_lib/__init__.py rename to tests/__init__.py diff --git a/tests/test_lib/polyfill/__init__.py b/tests/polyfill/__init__.py similarity index 100% rename from tests/test_lib/polyfill/__init__.py rename to tests/polyfill/__init__.py diff --git a/tests/test_lib/polyfill/test_h3.py b/tests/polyfill/test_h3.py similarity index 75% rename from tests/test_lib/polyfill/test_h3.py rename to tests/polyfill/test_h3.py index 6327cf8..50728d3 100644 --- a/tests/test_lib/polyfill/test_h3.py +++ b/tests/polyfill/test_h3.py @@ -119,106 +119,64 @@ def test_polygon_to_cells(): def test_polygon_to_cells_experimental(): poly = h3.LatLngPoly(sf_7x7) - # Note that `polygon_to_cells_experimental` is an alias for - # `h3shape_to_cells_experimental` - out = h3.polygon_to_cells_experimental(poly, res=9, contain='center') + for flags in [0, 'containment_center', h3.ContainmentMode.containment_center]: + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) - assert len(out) == 1253 - assert '89283080527ffff' in out - assert '89283095edbffff' in out + assert len(out) == 1253 + assert '89283080527ffff' in out + assert '89283095edbffff' in out -def test_h3shape_to_cells_experimental(): +def test_polygon_to_cells_experimental_full(): poly = h3.LatLngPoly(sf_7x7) + for flags in [1, 'containment_full', h3.ContainmentMode.containment_full]: + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) - out = h3.h3shape_to_cells_experimental(poly, res=9, contain='center') - - assert len(out) == 1253 - assert '89283080527ffff' in out - assert '89283095edbffff' in out + assert len(out) == 1175 + assert '89283082a1bffff' in out + assert '89283080527ffff' not in out + assert '89283095edbffff' in out -def test_h3shape_to_cells_experimental_full(): +def test_polygon_to_cells_experimental_overlapping(): poly = h3.LatLngPoly(sf_7x7) + for flags in [ + 2, + 'containment_overlapping', + h3.ContainmentMode.containment_overlapping + ]: + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) - out = h3.h3shape_to_cells_experimental(poly, res=9, contain='full') - - assert len(out) == 1175 - assert '89283082a1bffff' in out - assert '89283080527ffff' not in out - assert '89283095edbffff' in out + assert len(out) == 1334 + assert '89283080527ffff' in out + assert '89283095edbffff' in out -def test_h3shape_to_cells_experimental_overlapping(): +def test_polygon_to_cells_experimental_overlapping_bbox(): poly = h3.LatLngPoly(sf_7x7) + for flags in [ + 3, + 'containment_overlapping_bbox', + h3.ContainmentMode.containment_overlapping_bbox + ]: + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) - out = h3.h3shape_to_cells_experimental(poly, res=9, contain='overlap') - - assert len(out) == 1334 - assert '89283080527ffff' in out - assert '89283095edbffff' in out + assert len(out) == 1416 + assert '89283080527ffff' in out + assert '89283095edbffff' in out -def test_h3shape_to_cells_experimental_overlapping_bbox(): +def test_polygon_to_cells_experimental_invalid_mode(): poly = h3.LatLngPoly(sf_7x7) - out = h3.h3shape_to_cells_experimental(poly, res=9, contain='bbox_overlap') - - assert len(out) == 1416 - assert '89283080527ffff' in out - assert '89283095edbffff' in out - - -def test_h3shape_to_cells_experimental_invalid_mode(): - poly = h3.LatLngPoly(sf_7x7) - with pytest.raises(KeyError): - h3.h3shape_to_cells_experimental( - poly, - res = 9, - contain = 'contain_overlapping_bbox_abc', - ) - - -def test_poly_to_cells_experimental_mpoly(): - mpoly = h3.LatLngMultiPoly( - h3.LatLngPoly(sf_hole1), - h3.LatLngPoly(sf_hole2), - ) - - assert ( - set(h3.h3shape_to_cells_experimental(mpoly, res=9)) - == - set(h3.h3shape_to_cells_experimental(mpoly, res=9, contain='center')) - ) - - assert ( - set(h3.h3shape_to_cells_experimental(mpoly, res=9)) - < - set(h3.h3shape_to_cells_experimental( - mpoly, - res = 9, - contain = 'overlap' - )) - ) - - assert 120 == len(h3.h3shape_to_cells_experimental( - mpoly, - res = 9, - contain = 'overlap' - )) - - -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 + for flags in [1.0, 'containment_overlapping_bbox_abc', None]: + with pytest.raises(ValueError): + print(flags) + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + h3.polygon_to_cells_experimental(poly, res=9, flags=flags) def test_polyfill_with_hole(): @@ -316,23 +274,6 @@ 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/polyfill/test_polyfill.py similarity index 95% rename from tests/test_lib/polyfill/test_polyfill.py rename to tests/polyfill/test_polyfill.py index f70c639..1431b87 100644 --- a/tests/test_lib/polyfill/test_polyfill.py +++ b/tests/polyfill/test_polyfill.py @@ -145,15 +145,9 @@ def test_bad_geo_input(): with pytest.raises(ValueError): h3.h3shape_to_cells('not a shape', 9) - with pytest.raises(ValueError): - h3.h3shape_to_cells_experimental('not a shape', res=9) - 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_polyfill_ordering.py b/tests/polyfill/test_polyfill_ordering.py similarity index 100% rename from tests/test_lib/polyfill/test_polyfill_ordering.py rename to tests/polyfill/test_polyfill_ordering.py diff --git a/tests/test_lib/polyfill/test_polygon_class.py b/tests/polyfill/test_polygon_class.py similarity index 64% rename from tests/test_lib/polyfill/test_polygon_class.py rename to tests/polyfill/test_polygon_class.py index a3639b6..3996d30 100644 --- a/tests/test_lib/polyfill/test_polygon_class.py +++ b/tests/polyfill/test_polygon_class.py @@ -44,22 +44,5 @@ def test_bad_subclass(): shoop = H3Shoop() shoop.__geo_interface__() - with pytest.raises(ValueError): h3.h3shape_to_cells(shoop, res=9) - - 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/polyfill/test_to_multipoly.py b/tests/polyfill/test_to_multipoly.py new file mode 100644 index 0000000..61f77f6 --- /dev/null +++ b/tests/polyfill/test_to_multipoly.py @@ -0,0 +1,49 @@ +import h3 + + +from .. import util as u + + +def test_cells_to_h3shape(): + h = '8928308280fffff' + cells = h3.grid_disk(h, 1) + + mpoly = h3.cells_to_h3shape(cells, tight=False) + poly = mpoly[0] + + poly2 = h3.LatLngPoly(poly.outer, *poly.holes) + out = h3.h3shape_to_cells(poly2, 9) + + assert u.same_set(out, cells) + + +def test_cells_to_h3shape_tight(): + h = '8928308280fffff' + cells = h3.grid_disk(h, 1) + + poly = h3.cells_to_h3shape(cells, tight=True) + poly2 = h3.LatLngPoly(poly.outer, *poly.holes) + out = h3.h3shape_to_cells(poly2, 9) + + assert u.same_set(out, cells) + + +def test_2_polys(): + h = '8928308280fffff' + cells = h3.grid_ring(h, 2) + cells = cells + [h] + # cells should be a center hex, and the 2-ring around it + # (with the 1-ring being absent) + + mpoly = h3.cells_to_h3shape(cells) + + out = [ + set(h3.h3shape_to_cells(poly, 9)) + for poly in mpoly + ] + + assert u.same_set( + set.union(*out), + cells + ) + assert set(map(len, out)) == {1, 12} diff --git a/tests/readme.md b/tests/readme.md deleted file mode 100644 index 0aba346..0000000 --- a/tests/readme.md +++ /dev/null @@ -1,18 +0,0 @@ -We separate the `h3-py` tests into two groups, organized by subfolder. - -We do this because we expect 100% coverage on the library tests, but are -still working through getting full coverage on the Cython tests. - - -## `test_lib` - -The tests in this folder are for the main `h3-py` Python API for folks -who are using the pure-Python library functionality. - -## `test_cython` - -The tests in this folder are for the advanced Cython API, that allows -for other *Cython* packages or scripts to use the Cython code provided -by the `h3-py` internals. - -Note that the "Cython API" of `h3-py` is not currently externally supported. diff --git a/tests/test_lib/test_apis/__init__.py b/tests/test_apis/__init__.py similarity index 100% rename from tests/test_lib/test_apis/__init__.py rename to tests/test_apis/__init__.py diff --git a/tests/test_lib/test_apis/test_api_bindings_match.py b/tests/test_apis/test_api_bindings_match.py similarity index 100% rename from tests/test_lib/test_apis/test_api_bindings_match.py rename to tests/test_apis/test_api_bindings_match.py diff --git a/tests/test_apis/test_basic_int.py b/tests/test_apis/test_basic_int.py new file mode 100644 index 0000000..a567b3d --- /dev/null +++ b/tests/test_apis/test_basic_int.py @@ -0,0 +1,34 @@ +import h3.api.basic_int as h3 + + +from .. import util as u + + +def test_int_output(): + lat = 37.7752702151959 + lng = -122.418307270836 + + assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 + assert h3.latlng_to_cell(lat, lng, 9) == 0x8928308280fffff + + +def test_grid_disk(): + expected = [ + 617700169957507071, + 617700169957769215, + 617700169958031359, + 617700169958293503, + 617700169961177087, + 617700169964847103, + 617700169965109247, + ] + + out = h3.grid_disk(617700169958293503, 1) + assert u.same_set(out, expected) + + +def test_compact_cells(): + h = 617700169958293503 + cells = h3.cell_to_children(h) + + assert h3.compact_cells(cells) == [h] diff --git a/tests/test_lib/test_apis/test_basic_str.py b/tests/test_apis/test_basic_str.py similarity index 100% rename from tests/test_lib/test_apis/test_basic_str.py rename to tests/test_apis/test_basic_str.py diff --git a/tests/test_lib/test_apis/test_collection_inputs.py b/tests/test_apis/test_collection_inputs.py similarity index 100% rename from tests/test_lib/test_apis/test_collection_inputs.py rename to tests/test_apis/test_collection_inputs.py diff --git a/tests/test_lib/test_apis/test_ico_faces.py b/tests/test_apis/test_ico_faces.py similarity index 100% rename from tests/test_lib/test_apis/test_ico_faces.py rename to tests/test_apis/test_ico_faces.py diff --git a/tests/test_apis/test_memview_int.py b/tests/test_apis/test_memview_int.py new file mode 100644 index 0000000..0523794 --- /dev/null +++ b/tests/test_apis/test_memview_int.py @@ -0,0 +1,25 @@ +import h3.api.memview_int as h3 + + +def test1(): + lat, lng = 37.7752702151959, -122.418307270836 + assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 + + +def test_line(): + h1 = '8928308280fffff' + h2 = '8928308287bffff' + h1, h2 = h3.str_to_int(h1), h3.str_to_int(h2) + + out = h3.grid_path_cells(h1, h2) + + # todo: are we outputting `memoryviewslice`? should we just output a memoryview? + assert 'memoryview' in str(type(out)) + + expected = [ + 617700169958293503, + 617700169964847103, + 617700169965371391, + ] + + assert list(out) == expected diff --git a/tests/test_lib/test_apis/test_numpy_int.py b/tests/test_apis/test_numpy_int.py similarity index 65% rename from tests/test_lib/test_apis/test_numpy_int.py rename to tests/test_apis/test_numpy_int.py index 6bcd0b6..c341b55 100644 --- a/tests/test_lib/test_apis/test_numpy_int.py +++ b/tests/test_apis/test_numpy_int.py @@ -50,17 +50,3 @@ 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_cells_and_edges.py similarity index 73% rename from tests/test_lib/test_cells_and_edges.py rename to tests/test_cells_and_edges.py index 65d9d13..f918019 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_cells_and_edges.py @@ -8,10 +8,6 @@ from h3 import ( H3ResMismatchError, H3CellInvalidError, H3NotNeighborsError, - H3DigitDomainError, - H3BaseCellDomainError, - H3DeletedDigitError, - H3IndexInvalidError, ) @@ -131,7 +127,9 @@ def test_parent_err(): except Exception as e: msg = str(e) - expected = f'Invalid parent resolution -1 for cell 0x{h}.' + # todo: revist this weird formatting stuff + expected = 'Invalid parent resolution -1 for cell {}.' + expected = expected.format(hex(h3.str_to_int(h))) assert msg == expected @@ -454,12 +452,8 @@ def test_versions(): v_c = Version(v['c']) v_p = Version(v['python']) - # 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] + # of X.Y.Z, X and Y must match + assert v_c.release[:2] == v_p.release[:2] def test_str_int_convert(): @@ -480,14 +474,6 @@ 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) @@ -611,163 +597,3 @@ 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_error_codes.py similarity index 65% rename from tests/test_lib/test_error_codes.py rename to tests/test_error_codes.py index 4ae1d37..9961178 100644 --- a/tests/test_lib/test_error_codes.py +++ b/tests/test_error_codes.py @@ -1,10 +1,6 @@ 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? @@ -16,30 +12,24 @@ 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_h3.py b/tests/test_h3.py similarity index 100% rename from tests/test_lib/test_h3.py rename to tests/test_h3.py diff --git a/tests/test_lib/test_length_area.py b/tests/test_length_area.py similarity index 80% rename from tests/test_lib/test_length_area.py rename to tests/test_length_area.py index ca38257..1003f56 100644 --- a/tests/test_lib/test_length_area.py +++ b/tests/test_length_area.py @@ -86,30 +86,6 @@ 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' diff --git a/tests/test_lib/polyfill/test_to_multipoly.py b/tests/test_lib/polyfill/test_to_multipoly.py deleted file mode 100644 index 80c5a75..0000000 --- a/tests/test_lib/polyfill/test_to_multipoly.py +++ /dev/null @@ -1,360 +0,0 @@ -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) - - mpoly = h3.cells_to_h3shape(cells, tight=False) - poly = mpoly[0] - - poly2 = h3.LatLngPoly(poly.outer, *poly.holes) - out = h3.h3shape_to_cells(poly2, 9) - - assert u.same_set(out, cells) - - -def test_cells_to_h3shape_tight(): - h = '8928308280fffff' - cells = h3.grid_disk(h, 1) - - poly = h3.cells_to_h3shape(cells, tight=True) - poly2 = h3.LatLngPoly(poly.outer, *poly.holes) - out = h3.h3shape_to_cells(poly2, 9) - - assert u.same_set(out, cells) - - -def test_2_polys(): - h = '8928308280fffff' - cells = h3.grid_ring(h, 2) - cells = cells + [h] - # cells should be a center hex, and the 2-ring around it - # (with the 1-ring being absent) - - mpoly = h3.cells_to_h3shape(cells) - - out = [ - set(h3.h3shape_to_cells(poly, 9)) - for poly in mpoly - ] - - assert u.same_set( - set.union(*out), - 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 deleted file mode 100644 index 3f3b14c..0000000 --- a/tests/test_lib/test_apis/test_basic_int.py +++ /dev/null @@ -1,56 +0,0 @@ -import h3.api.basic_int as h3 - - -from .. import util as u - - -def test_int_output(): - lat = 37.7752702151959 - lng = -122.418307270836 - - assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 - assert h3.latlng_to_cell(lat, lng, 9) == 0x8928308280fffff - - -def test_grid_disk(): - expected = [ - 617700169957507071, - 617700169957769215, - 617700169958031359, - 617700169958293503, - 617700169961177087, - 617700169964847103, - 617700169965109247, - ] - - out = h3.grid_disk(617700169958293503, 1) - assert u.same_set(out, expected) - - -def test_compact_cells(): - h = 617700169958293503 - 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 deleted file mode 100644 index f608f54..0000000 --- a/tests/test_lib/test_apis/test_memview_int.py +++ /dev/null @@ -1,39 +0,0 @@ -import h3.api.memview_int as h3 - - -def test1(): - lat, lng = 37.7752702151959, -122.418307270836 - assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 - - -def test_line(): - h1 = '8928308280fffff' - h2 = '8928308287bffff' - h1, h2 = h3.str_to_int(h1), h3.str_to_int(h2) - - out = h3.grid_path_cells(h1, h2) - - # todo: are we outputting `memoryviewslice`? should we just output a memoryview? - assert 'memoryview' in str(type(out)) - - expected = [ - 617700169958293503, - 617700169964847103, - 617700169965371391, - ] - - 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_geojson_containers.py b/tests/test_lib/test_geojson_containers.py deleted file mode 100644 index a890c27..0000000 --- a/tests/test_lib/test_geojson_containers.py +++ /dev/null @@ -1,62 +0,0 @@ -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/util.py b/tests/util.py similarity index 100% rename from tests/test_lib/util.py rename to tests/util.py